@keb-org/consol 0.0.0-stage → 0.1.1

package/dist/index.mjs

@@ -0,0 +1,5 @@
+// Thin ESM wrapper over the one CommonJS implementation: import and require share every class,
+// so instanceof and ConsolError.is() agree. Types come from index.d.ts for both.
+import sdk from "./index.js";
+
+export const { Consol, ConsolError, Vault, createVault, openVault, httpStatus, sliceUtf8 } = sdk;

package/dist/stdio.d.ts

@@ -0,0 +1,120 @@
+import { type CallOptions, type Context, type Transport } from "./transport";
+import type { Reply } from "./types";
+/** Bound of the kept stderr tail and of any one line, in UTF-8 bytes. */
+export declare const STDERR_TAIL_BYTES = 4096;
+/** Any OpenAI-shaped `/embeddings` endpoint; without it recall stays lexical-only. */
+export interface EmbeddingOptions {
+    url: string;
+    /** Omit for endpoints that take no key. */
+    apiKey?: string;
+    model: string;
+    dims?: number;
+    queryPrefix?: string;
+    batchSize?: number;
+    timeoutMs?: number;
+}
+/** Jev advice (experimental). */
+export interface JevOptions {
+    url?: string;
+    apiKey?: string;
+    model?: string;
+    /** `false` turns automatic triage off. */
+    auto?: boolean;
+}
+/**
+ * What starts the `consol stdio` child. Options become the child's environment (never argv);
+ * inherited CONSOL_* and RUST_LOG are stripped first and `env` is applied last.
+ */
+export interface EngineOptions {
+    /** Database URL: PostgreSQL with pgvector, or CockroachDB. Without it this process's `CONSOL_DB_URL` applies; the child needs one. */
+    db?: string;
+    embedding?: EmbeddingOptions;
+    jev?: JevOptions;
+    /** Explicit binary; otherwise CONSOL_BIN, the platform package, then PATH. */
+    binaryPath?: string;
+    env?: Record<string, string>;
+    /** Default per-call deadline in ms (300000); 0 disables it. */
+    timeoutMs?: number;
+    /** Receives each child stderr line. Without it lines are only kept for error messages. */
+    onLog?: (line: string) => void;
+}
+export declare function engineEnv(o: EngineOptions): Record<string, string>;
+export interface StdioOptions extends EngineOptions {
+    /** `--vault PATH` or `--vault-root ROOT`. */
+    location: ["--vault" | "--vault-root", string];
+    /** After the ready line: create (first start only) or open this vault. A restart always opens. */
+    boot?: {
+        vault: string;
+        create: boolean;
+    };
+    /** The SDK version the child's major.minor must match. */
+    sdkVersion: string;
+}
+export interface BinaryResolution {
+    path: string;
+    attempts: string[];
+}
+/**
+ * Explicit path authoritative (missing file fails here), then CONSOL_BIN authoritative, then the
+ * platform package resolved relative to this SDK file, then PATH. CONSOL_BIN is read only here,
+ * never sent to the child.
+ */
+export declare function resolveBinary(explicit?: string): BinaryResolution;
+/** Child env: host minus ALL CONSOL_* and RUST_LOG, then options, then explicit env last. */
+export declare function childEnv(base?: Record<string, string>, extra?: Record<string, string>): Record<string, string>;
+/** The last STDERR_TAIL_BYTES bytes of `text`, cut on a character boundary. */
+export declare function lastBytes(text: string): string;
+/**
+ * One `consol stdio` child speaking JSON lines (docs W-wire): a ready line, then `{id, op, ...}`
+ * frames answered by `{id, reply}` lines in any order. Stdin EOF ends the child gracefully.
+ */
+export declare class StdioTransport implements Transport {
+    private readonly opts;
+    private readonly attempts;
+    private readonly binary;
+    private readonly timeoutMs;
+    private child;
+    private reader;
+    private generation;
+    private nextId;
+    private pending;
+    private starting;
+    /** After the first successful start, every restart opens the vault instead of creating it. */
+    private started;
+    private closed;
+    private closing;
+    private stderrTail;
+    private stderrTailBytes;
+    version: string | null;
+    constructor(opts: StdioOptions);
+    private decoder;
+    private stderrPartial;
+    private onStderr;
+    private flushStderr;
+    private pushLine;
+    private tailText;
+    /**
+     * Idle children are unref'd so a forgotten close() never keeps Node or Bun alive. Only the process
+     * handle toggles (its stdio is unref'd once at spawn): Bun cannot unref a stream again once ref'd.
+     */
+    private updateRef;
+    private onDeath;
+    /**
+     * Final and idempotent: in-flight calls reject now, later calls with `closed`. Every close()
+     * returns the same promise, settled once the child has exited.
+     */
+    close(): Promise<void>;
+    private shutdown;
+    /** Starts the child and waits for its ready line, unless one is running or starting already. */
+    start(): Promise<void>;
+    private spawn;
+    private onLine;
+    /** Waits for the answer to `id`, writing `frame` first unless it is null (the ready line). */
+    private call;
+    /** One frame; after a crash the next call starts the child once more. Never retried. */
+    private send;
+    /** Runs one envelope under `ctx`. The reply is returned untouched, tool errors included. */
+    handle(body: unknown, ctx: Context, options?: CallOptions): Promise<Reply>;
+    /** Create or open a vault by name; a refusal arrives as the reply's `vault_exists` / `vault_not_found`. */
+    vaultOp(op: "create_vault" | "open_vault", vault: string, options?: CallOptions): Promise<Reply>;
+}

package/dist/transport.d.ts

@@ -0,0 +1,38 @@
+import type { Reply } from "./types";
+export declare const DEFAULT_TIMEOUT_MS = 300000;
+export interface CallOptions {
+    signal?: AbortSignal;
+    /** Per-call deadline in ms; 0 disables it. Defaults to the vault's `timeoutMs`. */
+    timeoutMs?: number;
+}
+/** What a backend knows about the caller; it comes from the developer's own auth, never from a request. */
+export interface Context {
+    /** Vaults the caller may use; `null` means any vault, on purpose. */
+    vaults: string[] | null;
+    /** Pins the agent; the request cannot name another one. */
+    agent?: string | null;
+}
+/** One way to move an envelope: a stdio child or HTTP. Internal: only Vault and Consol are public. */
+export interface Transport {
+    /** Server version of the last reply; null before the first. */
+    readonly version: string | null;
+    handle(body: unknown, ctx: Context, options?: CallOptions): Promise<Reply>;
+    /** Final and idempotent. */
+    close(): Promise<void>;
+}
+/** A deadline is a non-negative integer of ms; 0 disables it. */
+export declare function deadline(ms: number | undefined, fallback: number): number;
+/** Server major.minor must equal the SDK's; returns the server version. */
+export declare function checkVersion(got: unknown, sdk: string): string;
+/** POSTs the envelope to `url`; the caller's headers are the backend's auth. Stateless. */
+export declare class HttpTransport implements Transport {
+    private readonly url;
+    private readonly headers;
+    private readonly timeoutMs;
+    private readonly sdkVersion;
+    version: string | null;
+    private readonly closed;
+    constructor(url: string, headers: Record<string, string>, timeoutMs: number, sdkVersion: string);
+    handle(body: unknown, _ctx: Context, options?: CallOptions): Promise<Reply>;
+    close(): Promise<void>;
+}

package/dist/types.d.ts

@@ -0,0 +1,395 @@
+import type { ConsolErrorCode } from "./errors";
+/** Open enum: autocompletes the known values and still accepts future ones. */
+type Open<T extends string> = T | (string & {});
+/**
+ * The wire reply, the same on every transport. `text` is rendered for an LLM, `result` is the
+ * contract payload (receipt fields next to `error` for a failed reflection-bound write). Tool
+ * errors are replies with `error`, never exceptions.
+ */
+export interface Reply {
+    version: string;
+    /** Guidance for an LLM; absent when there is none. Note Markdown is not here: it is inline in `result`. */
+    text?: string;
+    result?: unknown;
+    error?: ToolError;
+    [key: string]: unknown;
+}
+/** Structured tool error (contract section 4); failed reflect entries carry the same shape. */
+export interface ToolError {
+    code: ConsolErrorCode;
+    retryable: boolean;
+    message: string;
+    /** Input at fault as a path, e.g. `decisions[2].temporal.evidence[0]`; only when one input is to blame. */
+    field?: string;
+}
+/** Part of a successful call that could not be done; an empty list means nothing was degraded. */
+export interface Unavailable {
+    code: Open<"source_invalid" | "embedding_unavailable" | "index_unavailable" | "relationships_incomplete">;
+    count?: number;
+}
+/** Note status: `active`, an authored status such as `archived`, or a computed one. */
+export type Status = Open<"active" | "archived" | "superseded" | "expired" | "not_yet_valid" | "empty_validity" | "invalid_validity">;
+/** UTF-8 byte offsets `[start, end)` into the source text, not JS string indices. */
+export type ByteRange = [number, number];
+/** Consolidation level of a note; it says nothing about truth or trust. */
+export type Scope = "records" | "episodic" | "semantic" | "skills" | "core";
+/** Exact note version; pass `content_version` back as `expected_version` so writes never clobber unseen edits. */
+export interface SourceRef {
+    id: string;
+    owner: string;
+    content_version: string;
+    /** Present only when the server could hash the note's review dependencies too. */
+    review_version?: string;
+}
+/** Link kinds (open); bare `[[x]]` links are `wikilink` (or `hub_member` inside a hub). */
+export type RelationshipKind = Open<"derives" | "causes" | "contradicts" | "questions" | "wikilink" | "hub_member">;
+/** Recorded link, never a truth vote; statuses and validity bounds tell whether each endpoint is current. */
+export interface Relationship {
+    kind: RelationshipKind;
+    direction: "outgoing" | "incoming" | "contextual";
+    owner_source: SourceRef;
+    src: string;
+    dst: string;
+    src_source: SourceRef;
+    dst_source: SourceRef;
+    owner_status: Status;
+    src_status: Status;
+    dst_status: Status;
+    owner_valid_from_ms: number | null;
+    owner_valid_to_ms: number | null;
+    src_valid_from_ms: number | null;
+    src_valid_to_ms: number | null;
+    dst_valid_from_ms: number | null;
+    dst_valid_to_ms: number | null;
+    reasons?: string[];
+}
+/** `read` payload; `text` is the complete file, byte for byte, frontmatter included. */
+export interface ReadResult {
+    text: string;
+    source: SourceRef;
+    source_path: string;
+    scope: Scope;
+    status: Status;
+    valid_from_ms: number | null;
+    valid_to_ms: number | null;
+    /** One page of 16; pass `continuation` back to read the next page (null on the last). */
+    relationships: Relationship[];
+    continuation: string | null;
+    unavailable: Unavailable[];
+}
+/** Retrieval arm (open); `linked` cards were pulled in by a contradiction or tension link. */
+export type RecallRetrieval = Open<"exact" | "ledger" | "facet" | "fused" | "relaxed" | "linked">;
+/** `text` is exactly the bytes at `byte_range` of the note version in `source.content_version`. */
+export interface SourceExcerpt {
+    byte_range: ByteRange;
+    text: string;
+    heading_context?: string;
+    speaker_date_context?: string;
+}
+/** A search lead, not proof: read the source before relying on or editing it. */
+export interface RecallCard {
+    source: SourceRef;
+    scope: Scope;
+    status: Status;
+    retrieval: RecallRetrieval;
+    tier: "full" | "lead" | "id" | "linked";
+    matched_passages: number;
+    valid_from_ms: number | null;
+    valid_to_ms: number | null;
+    /** When the event happened, from the note's leading `[Date: …]` line; null when unknown. */
+    observed_ms: number | null;
+    summary?: string;
+    excerpts?: SourceExcerpt[];
+    relationships?: Relationship[];
+    linked_via?: string;
+    compact?: boolean;
+}
+/** Every `jev`, `jev_triage` and `jev_advisory` field is experimental: present only with Jev configured. */
+export type Experimental = Record<string, unknown>;
+/** `recall` payload: at most `limit` cards, linked companions included. */
+export interface RecallResult {
+    /**
+     * The progressive disclosure as a model reads it: full cards with excerpts, lead and id cards,
+     * the question's intent block and the hints. `candidates` are the same cards as data.
+     */
+    text: string;
+    candidates: RecallCard[];
+    /** True when more matched cards or companions were omitted. */
+    truncated: boolean;
+    unavailable: Unavailable[];
+    jev?: Experimental;
+}
+/** Similar note worth inspecting after a write; similarity is never agreement. */
+export interface AffectedDoc {
+    id: string;
+    source_path: string;
+    similarity: number;
+    valid_to_ms: number | null;
+}
+/** Notes sharing an entity with the written note. */
+export interface EntityAffectedGroup {
+    entity: string;
+    docs: AffectedDoc[];
+}
+/** `remember` receipt; a reflection-bound write adds `reflection_write` to this same shape. */
+export interface RememberResult {
+    changed: boolean;
+    indexed: boolean;
+    /** Present when publication is known. */
+    source?: SourceRef;
+    source_path?: string;
+    /** Parsed validity bounds, echoed. */
+    valid_from_ms: number | null;
+    valid_to_ms: number | null;
+    invalidated_dependents: string[];
+    affected: AffectedDoc[];
+    entity_affected: EntityAffectedGroup[];
+    unavailable: Unavailable[];
+    /** Outcome of a reflection-bound write (and of the resume form). */
+    reflection_write?: WriteOutcome;
+    jev?: Experimental;
+}
+/** `remove` receipt: the note is archived, its body stays readable and editable. */
+export interface RemoveResult {
+    changed: boolean;
+    indexed: boolean;
+    source?: SourceRef;
+    source_path?: string;
+    /** Validity bounds of the archived version. */
+    valid_from_ms: number | null;
+    valid_to_ms: number | null;
+    invalidated_dependents: string[];
+    unavailable: Unavailable[];
+    reflection_write?: WriteOutcome;
+    jev?: Experimental;
+}
+/** Durable state of a reflection-bound write (open); only `succeeded` published bytes. */
+export type WriteState = Open<"pending" | "succeeded" | "conflicted" | "abandoned">;
+/** Why a reflection write has not succeeded yet (open); resume or abandon it explicitly. */
+export type WriteFailureCode = Open<"source_conflict" | "basis_changed" | "index_pending" | "publication_pending" | "receipt_pending">;
+/** Proof of a published reflection write. */
+export interface WriteReceipt {
+    operation: "remember" | "remove";
+    source_path: string;
+    before: SourceRef | null;
+    after: SourceRef;
+    indexed: boolean;
+}
+/** Recorded reason a write was abandoned; `inspected: null` means the target was absent. */
+export interface WriteResolution {
+    inspected: SourceRef | null;
+    reason: string;
+}
+/** Outcome of one reflection-bound write; a write never completes the work by itself. */
+export interface WriteOutcome {
+    work_id: string;
+    action_key: string;
+    state: WriteState;
+    /** True for a replayed terminal outcome: it describes history, not the current source. */
+    historical: boolean;
+    saved: boolean | null;
+    indexed: boolean;
+    receipt: WriteReceipt | null;
+    resolution: WriteResolution | null;
+    failure_code: WriteFailureCode | null;
+}
+/** Queue state of a work item; only an accepted decision completes it. */
+export type WorkStatus = "pending" | "completed" | "blocked" | "retryable" | "stale";
+/** Pair found through a link authored in `owner`. */
+export interface AuthoredLead {
+    route: "authored";
+    owner: SourceRef;
+    src: string;
+    dst: string;
+    relation: "derives" | "causes" | "contradicts" | "questions" | "hub_member";
+}
+/** Pair found through a shared facet value. */
+export interface SharedFacetLead {
+    route: "shared_facet";
+    value: string;
+}
+/** Pair found through a shared numeric value. */
+export interface SharedNumericLead {
+    route: "shared_numeric";
+    value: string;
+}
+/** Pair found through embedding similarity (embeddings on only). */
+export interface SemanticLead {
+    route: "semantic";
+    probe: SourceRef;
+    target: SourceRef;
+    entity_hash: string;
+    projection_hash: string;
+    fingerprint: string;
+    score: number;
+}
+/** Discovery witness of a pair; one witness, not an exhaustive list or a truth judgment. */
+export type PairLead = AuthoredLead | SharedFacetLead | SharedNumericLead | SemanticLead;
+/** Hub witness; `target` is null when a new hub would be formed. Unstable: checked against Rust source only. */
+export interface HubLead {
+    route: "hub";
+    target: string | null;
+    members: string[];
+    witness: string;
+    coverage: string[];
+    constraint: string | null;
+}
+/** Promotion witness. Unstable: checked against Rust source only. */
+export interface PromotionLead {
+    route: "promotion";
+    entity: string;
+    scope: "skills" | "core";
+    existing: string[];
+}
+/** Sources a work item was judged on; the basis hash binds decisions to exactly these versions. */
+export interface WorkBasis<L> {
+    subjects: SourceRef[];
+    sources: SourceRef[];
+    lead: L;
+}
+/** Shared by every work kind, so they stay readable before narrowing on `kind`. */
+export interface WorkBase {
+    work_id: string;
+    basis_hash: string;
+    status: WorkStatus;
+}
+/** Review one note; source work carries no lead. */
+export interface SourceWork extends WorkBase {
+    kind: "source";
+    basis: {
+        subjects: SourceRef[];
+        sources: SourceRef[];
+    };
+}
+/** Compare two notes. */
+export interface PairWork extends WorkBase {
+    kind: "pair";
+    basis: WorkBasis<PairLead>;
+}
+/** Form, attach to or bridge a hub. Unstable: checked against Rust source only. */
+export interface HubWork extends WorkBase {
+    kind: "hub_attachment" | "hub_formation" | "hub_bridge";
+    basis: WorkBasis<HubLead>;
+}
+/** Promote recurring knowledge to skills/core. Unstable: checked against Rust source only. */
+export interface PromotionWork extends WorkBase {
+    kind: "promotion";
+    basis: WorkBasis<PromotionLead>;
+}
+/** A delivered work item, discriminated on `kind`. */
+export type ReflectionWork = SourceWork | PairWork | HubWork | PromotionWork;
+/** Markdown block of a delivered source, as a suggested excerpt boundary. */
+export interface CandidateBlock {
+    byte_range: ByteRange;
+    heading_context: string | null;
+    speaker_date_context: string | null;
+}
+/** A delivered source: `text` is its complete original Markdown (inline in the reply). */
+export interface DeliveredSource {
+    source: SourceRef;
+    text: string;
+    byte_range: ByteRange;
+    /** Suggested body spans, not a replacement for inspection. */
+    candidate_blocks: CandidateBlock[];
+}
+/** Work delivered with every source body; deliver, write and decide are separate steps. */
+export interface CompleteDelivery {
+    work: ReflectionWork;
+    sources: DeliveredSource[];
+    complete: true;
+    jev_advisory?: Experimental;
+}
+/** Work or a requested source that could not be delivered this call; the call itself succeeded. */
+export interface FailedDelivery {
+    /** Present when the work is known. */
+    work_id?: string;
+    /** Present for a requested source (`ids` mode). */
+    requested_id?: string;
+    complete: false;
+    error: ToolError;
+}
+/** One entry of `reflect().deliveries`; narrow on `complete`. */
+export type ReflectDelivery = CompleteDelivery | FailedDelivery;
+/** Allowed `disposition` values of a source decision. */
+export type SourceDisposition = "synthesize" | "connect" | "archive" | "retained_raw" | "blocked" | "retryable_error" | "stale";
+/** Allowed `disposition` values of a pair decision. */
+export type PairDisposition = "linked" | "no_relation" | "unresolved" | "blocked" | "retryable_error" | "stale";
+/** Allowed `disposition` values of a hub or promotion decision. */
+export type ConsolidationDisposition = "applied" | "reused" | "rejected" | "retained_raw" | "blocked" | "retryable_error" | "stale";
+/** Accepted source/pair/hub/promotion decision; `status` echoes the disposition. */
+export interface AcceptedDecision {
+    work_id: string;
+    accepted: true;
+    status: SourceDisposition | PairDisposition | ConsolidationDisposition;
+}
+/** Accepted `abandon_write`; the resulting outcome is in `writes`. */
+export interface AcceptedAbandon {
+    work_id: string;
+    action_key: string;
+    accepted: true;
+}
+/** Failed decision; the call still succeeds and later decisions still run. */
+export interface RejectedDecision {
+    work_id: string;
+    accepted: false;
+    error: ToolError;
+}
+/** One entry of `reflect().decisions`, in submission order. */
+export type DecisionReceipt = AcceptedDecision | AcceptedAbandon | RejectedDecision;
+/** Discovery lanes in the order the server reports them. */
+export type ReflectionLane = "source" | "semantic_pairs" | "structural_pairs" | "hubs" | "promotions";
+/** Progress of one discovery page. */
+export interface LaneCoverage {
+    exhausted: boolean;
+    processed: number;
+    blocked: number;
+    retryable: number;
+}
+/** Source lane progress; `validation_complete` covers re-checks of earlier work. */
+export interface SourceLaneCoverage extends LaneCoverage {
+    validation_complete: boolean;
+}
+/** Lane report of a discovery call; `current_complete` is set only when completion could be checked. */
+export type DiscoveryLane = {
+    lane: "source";
+    coverage: SourceLaneCoverage;
+    current_complete?: boolean;
+} | {
+    lane: "structural_pairs" | "semantic_pairs" | "hubs" | "promotions";
+    coverage: LaneCoverage;
+    current_complete?: boolean;
+} | {
+    lane: ReflectionLane;
+    exhausted: false;
+    error: ToolError;
+    current_complete?: boolean;
+};
+/** Queue counters; `done` is true only when every lane is exhausted and nothing is open. */
+export interface ReflectCounters {
+    pending: number;
+    blocked: number;
+    retryable: number;
+    unresolved_writes: number;
+    done: boolean;
+}
+/** `reflect` payload for every mode; unused sections are empty. Check `counters.done` before assuming nothing is left. */
+export interface ReflectResult {
+    deliveries: ReflectDelivery[];
+    decisions: DecisionReceipt[];
+    writes: WriteOutcome[];
+    /** Lanes are filled by discovery (no targets) only. */
+    discovery: {
+        completion_checked: boolean;
+        lanes: DiscoveryLane[];
+    };
+    counters: ReflectCounters;
+    jev?: Experimental;
+    jev_triage?: Experimental;
+}
+/**
+ * Slice a string by UTF-8 byte offsets, not JS string indices. Validates bounds
+ * and character boundaries. Contract byte ranges always point into the text returned
+ * by the server, so valid ranges never fail.
+ */
+export declare function sliceUtf8(text: string, start: number, end: number): string;
+export {};