@stateforge-labs/herdr 0.0.0-stage → 0.3.0

package/dist/constants.js

@@ -0,0 +1,294 @@
+// Role: every literal the library uses outside the generated modules, as as-const objects; no consumers in phase 1b.
+// Informs HERDR-ADR-0003 (layering) and plan section 3 ("every literal lives in constants.ts"), 3.1, 3.3 and 3.6.
+import { ServerCapability, SubscriptionType } from './herdr/generated/index.js';
+export { TOKEN_NAME_PATTERN } from './herdr/generated/names/token-name-pattern.js';
+// Environment variable names and the default socket location.
+export const HerdrEnv = {
+    Socket: 'HERDR_SOCKET',
+    Home: 'HOME',
+    Live: 'HERDR_LIVE',
+};
+// Path parts of the default herdr socket, ~/.config/herdr/herdr.sock.
+export const SocketPathPart = {
+    ConfigDir: '.config',
+    HerdrDir: 'herdr',
+    SocketFile: 'herdr.sock',
+};
+// Request timeout and the margin added to a long-poll timeout (plan 3.3 gives 10 s; the margin is new, the owner may tune it).
+export const Timeout = {
+    DefaultMs: 10_000,
+    LongPollMarginMs: 5_000,
+};
+// Reconnect backoff for held and subscription connections.
+export const Backoff = {
+    InitialMs: 1_000,
+    MaxMs: 30_000,
+    Factor: 2,
+    // A connection that stayed up this long resets the backoff to InitialMs.
+    StableResetMs: 60_000,
+};
+// Protocol compatibility policy: exact match by default, minimum is optional.
+export const ProtocolPolicy = {
+    Exact: 'exact',
+    Minimum: 'minimum',
+};
+// Queue overflow behaviour of a subscription (plan 3.6).
+export const Overflow = {
+    DropOldest: 'drop-oldest',
+    Fail: 'fail',
+};
+// Kinds of watch handle (plan 3.6; hand-kept, not generated).
+export const WatchKind = {
+    Live: 'live',
+    Frame: 'frame',
+};
+// Keys of PRESET_METHODS in names.ts.
+export const Presets = {
+    SessionsReader: 'SessionsReader',
+};
+// Prefix of subscription request ids.
+export const SUBSCRIBE_ID_PREFIX = 'sub';
+// Error message builders; functions, so the wording lives in one place.
+export const ErrorText = {
+    NoAck: (ms) => `no ack within ${ms}ms`,
+    Unavailable: (method, what) => `${method}: ${what}`,
+    NoResponse: (method, ms) => `${method}: no response within ${ms}ms`,
+    Aborted: (method) => `${method}: aborted`,
+    Unparseable: (method) => `${method}: unparseable response`,
+    ClosedBeforeResponse: (method) => `${method}: connection closed before a response`,
+    ClientClosed: (method) => `${method}: client is closed`,
+    SocketError: (method) => `${method}: socket error`,
+    CannotConnect: (path) => `cannot connect to herdr socket at ${path}`,
+    NoSocket: (path) => `no herdr socket at ${path}`,
+    ProtocolMismatch: (expected, actual) => `herdr protocol ${actual} is not supported (expected ${expected})`,
+    Unsupported: (method, capability) => `${method}: server lacks capability ${capability}`,
+    Refused: (method, message, code) => `${method}: ${message} [${code}]`,
+    SubscriptionEnded: (method) => `${method}: the server closed the subscription`,
+    NotImplemented: (what, lane) => `${what} is not implemented yet (owned by lane ${lane}, HERDR-ADR-0017)`,
+    NotAllowed: (method) => `${method}: not allowed on this client`,
+};
+// Error class names, set as `name` on each wire error class (so the names are not typed twice).
+export const ErrorName = {
+    Herdr: 'HerdrError',
+    Transport: 'HerdrTransportError',
+    ProtocolMismatch: 'ProtocolMismatchError',
+    UnsupportedByServer: 'UnsupportedByServerError',
+    SubscriptionEnded: 'SubscriptionEnded',
+    NotImplemented: 'NotImplementedError',
+    MalformedSchema: 'MalformedSchemaError',
+    UnsupportedWatch: 'UnsupportedWatchError',
+};
+// JSON field names of the NDJSON wire envelopes.
+export const WireField = {
+    Id: 'id',
+    Method: 'method',
+    Params: 'params',
+    Result: 'result',
+    Error: 'error',
+    Code: 'code',
+    Message: 'message',
+    Type: 'type',
+    Protocol: 'protocol',
+    Version: 'version',
+    Capabilities: 'capabilities',
+    Event: 'event',
+};
+// Prefix of request ids The id is an echo, not a correlation key (HERDR-ADR-0016 W1).
+export const REQUEST_ID_PREFIX = 'sdk';
+// Id herdr returns for an unparseable request, followed by a close (HERDR-ADR-0016 W3).
+export const EMPTY_REPLY_ID = '';
+// One NDJSON line ends with a newline.
+export const LINE_SEPARATOR = '\n';
+// Socket text encoding.
+export const TEXT_ENCODING = 'utf8';
+// Outcome of one call, reported to the onCall hook.
+export const CallOutcome = {
+    Answered: 'answered',
+    Refused: 'refused',
+    Transport: 'transport',
+};
+// Results of `typeof x`: a JSON object envelope, and a text value (the fake writes a string line as it is).
+export const TypeofTag = {
+    Object: 'object',
+    String: 'string',
+};
+// Test-kit facts of the minimal fake (not herdr facts). F6 and W3 values are the fake's own choice, not measured.
+export const Fake = {
+    DirPrefix: 'herdr-fake-',
+    SocketFile: 'herdr.sock',
+    Version: '0.9.5-fake',
+    UnknownMethodCode: 'unknown_method',
+    InvalidRequestCode: 'invalid_request',
+    // Delay between the two halves of a split subscribe ack (test convenience, splitAck).
+    SplitAckDelayMs: 5,
+};
+// Texts the fake puts in its own error envelopes.
+export const FakeText = {
+    UnknownMethod: (method) => `unknown method ${method}`,
+    InvalidRequest: 'unparseable request',
+};
+// Capabilities the fake's pong advertises when a test does not choose (the fake's own choice, not herdr's).
+export const DEFAULT_CAPABILITIES = {
+    [ServerCapability.DetachedServerDaemon]: true,
+    [ServerCapability.HealthCheck]: true,
+    [ServerCapability.LiveHandoff]: true,
+    [ServerCapability.SshAgentRegistration]: true,
+    [ServerCapability.SurfaceInterest]: true,
+};
+// What the fake does with one request line: stay silent, write a raw line, or write an envelope.
+export const AnswerKind = {
+    Silent: 'silent',
+    Raw: 'raw',
+    Envelope: 'envelope',
+};
+// Where one fake connection stands after its last answer (test-kit only): still open for requests, answered and ended,
+// a subscriber after its ack (pushes flow), or a held connection (class C; answers every request, stays open).
+export const ServedState = {
+    Fresh: 'fresh',
+    Answered: 'answered',
+    Subscriber: 'subscriber',
+    Held: 'held',
+};
+// ---------------------------------------------------------------------------------------------
+// Contract constants (HERDR-ADR-0017, docs/architecture/contracts.md). Locked: lanes read them, the architect amends them.
+// ---------------------------------------------------------------------------------------------
+// The `event` of a push frame whose kind this library does not know (HERDR-ADR-0016 P3). Not a herdr value, so it cannot collide.
+export const UNKNOWN_EVENT = '@stateforge-labs/herdr:unknown-event';
+// Kinds of change watchPaneSet emits (plan 3.6, HERDR-ADR-0016 W6).
+export const PaneSetKind = {
+    Added: 'added',
+    Removed: 'removed',
+    Frame: 'frame',
+};
+// Subscription types that need pane_id (HERDR-ADR-0016 W6). Not a hand copy that can drift: the contract test
+// test/types/contract/subscription-lists.ts fails to compile unless this list equals PerPaneSubscriptionType exactly.
+export const PER_PANE_SUBSCRIPTION_TYPES = [
+    SubscriptionType.PaneOutputMatched,
+    SubscriptionType.PaneAgentStatusChanged,
+    SubscriptionType.PaneScrollChanged,
+];
+// Every other subscription type: watch()'s default `subscriptions` (plan 3.6).
+export const GLOBAL_SUBSCRIPTION_TYPES = Object.values(SubscriptionType).filter((type) => !PER_PANE_SUBSCRIPTION_TYPES.includes(type));
+// herdr-drift exit codes (HERDR-ADR-0009; P5: could not look is 3, never 0).
+export const DriftExitCode = {
+    Clean: 0,
+    Drift: 1,
+    Usage: 2,
+    NotCovered: 3,
+};
+// What a schema source found (drift; HERDR-ADR-0009).
+export const SchemaReadKind = {
+    Found: 'found',
+    NotFound: 'not-found',
+    Unreadable: 'unreadable',
+};
+// The drift CLI outcome before its exit code (drift; HERDR-ADR-0009).
+export const DriftOutcomeKind = {
+    Usage: 'usage',
+    NotCovered: 'not-covered',
+    Report: 'report',
+};
+// _tag of each Effect error.
+export const EffectErrorTag = {
+    Refused: 'HerdrRefused',
+    Unavailable: 'HerdrUnavailable',
+    ProtocolMismatch: 'ProtocolMismatch',
+    Unsupported: 'HerdrUnsupported',
+};
+// Measured herdr wire facts the full fake reproduces (HERDR-ADR-0016 W1-W6).
+export const WireFact = {
+    W1CloseAfterResponse: 'W1',
+    W2AckThenStream: 'W2',
+    W3EmptyIdOnUnparseable: 'W3',
+    W4SchemaOverSocketIsEmpty: 'W4',
+    W5NoHistoryReplay: 'W5',
+    W6PerPaneNeedsPaneId: 'W6',
+};
+// Lanes of the parallel build (contracts.md). Used by notImplemented() so a stub names its owner.
+export const Lane = {
+    P2a: 'P2a',
+    P2b: 'P2b',
+    P3: 'P3',
+    P4a: 'P4a',
+    P4b: 'P4b',
+    P5a: 'P5a',
+    P5c: 'P5c',
+    P6a: 'P6a',
+};
+// ---------------------------------------------------------------------------------------------
+// Lane sections: a lane adds constants ONLY between its own `--- lane Px ---` and `--- end Px ---` lines (append-only;
+// contracts.md "shared files"). The blank lines between sections keep two lanes' inserts in separate merge hunks.
+// ---------------------------------------------------------------------------------------------
+// --- lane P2a ---
+// --- end P2a ---
+// --- lane P2b ---
+// Entry names of the scoped clients: the keys of the generated ENTRY_METHODS table (contracts.md, client/types.ts EntryName).
+export const EntryKey = {
+    client: 'client',
+    admin: 'admin',
+    prompt: 'prompt',
+    readOnly: 'readOnly',
+    readOnlyContent: 'readOnlyContent',
+    held: 'held',
+};
+// Separates the segments of a method name: `agent.view.set` is the leaf `set` under `agent` then `view`.
+export const METHOD_SEPARATOR = '.';
+// Keys of the namespace tree that the client composes by hand (events.subscribe is not a tree leaf).
+export const TreeKey = {
+    Events: 'events',
+    Subscribe: 'subscribe',
+};
+// Results of `typeof` that the namespace tree tells a branch from a leaf by.
+export const TypeofKind = {
+    Function: 'function',
+    Object: 'object',
+};
+// --- end P2b ---
+// --- lane P3 ---
+// --- end P3 ---
+// --- lane P4a ---
+// --- end P4a ---
+// --- lane P4b ---
+// Messages of the watch layer (plan 3.6, HERDR-ADR-0016 W5/W6). Codes stay in ErrorName; these are the texts only.
+export const WatchText = {
+    ReplayOverflow: (max) => `replay buffer overflowed at ${max} frames`,
+    OutputMatchUnsupported: 'watchPaneSet does not subscribe to pane.output_matched: its match and source are not options yet (HERDR-ADR-0016 open issue 8)',
+};
+// Messages of the held connection layer (plan 3.6).
+export const HeldText = {
+    Ended: (method) => `${method}: the held connection is closed`,
+};
+// Subscription types that keep watchPaneSet's set of panes (W6): a pane is created or closed.
+export const PANE_LIFECYCLE_SUBSCRIPTION_TYPES = [SubscriptionType.PaneCreated, SubscriptionType.PaneClosed];
+// --- end P4b ---
+// --- lane P5a ---
+// Error code the fake returns for params that break the generated shape, or a per-pane spec without pane_id (HERDR-ADR-0016 W6: herdr answers invalid_params).
+export const FakeErrorCode = { InvalidParams: 'invalid_params' };
+// Texts of the fake's invalid_params errors.
+export const FakeCheckText = {
+    NotAnObject: (method) => `${method}: params must be an object`,
+    MissingField: (method, field) => `${method}: missing required field ${field}`,
+    WrongKind: (method, field) => `${method}: field ${field} has the wrong type`,
+    NotInEnum: (method, field) => `${method}: field ${field} is not an allowed value`,
+    KeyNotAllowed: (method, field) => `${method}: a key of field ${field} is not allowed`,
+    NeedsPaneId: (type) => `${type} needs pane_id`,
+};
+// JavaScript typeof results the request checker compares a value against (the number and boolean ones; TypeofTag has the rest).
+export const TypeofValue = { Number: 'number', Boolean: 'boolean' };
+// The result herdr gives api.schema over the socket (HERDR-ADR-0016 W4, measured): an empty object.
+export const EMPTY_SCHEMA_RESULT = {};
+// Field names of a subscription spec (subscriptions, pane_id) that the fake reads.
+export const SpecField = { Subscriptions: 'subscriptions', PaneId: 'pane_id' };
+// Methods the fake answers that the generated schema does not list (api.schema is not in generated Method; W4).
+export const FakeMethod = { ApiSchema: 'api.schema' };
+// How an event kind is named as a subscription type: pane_created is subscription pane.created; a frame already named as a subscription type (pane.output_matched) keeps its name.
+export const NameSeparator = { Event: '_', Subscription: '.' };
+// --- end P5a ---
+// --- lane P5c ---
+// --- end P5c ---
+// --- lane P6a ---
+// Message of a tagged error whose source carries no message (a thrown string, undefined, a plain object).
+export const EffectFallbackMessage = {
+    UnknownError: 'unknown herdr error',
+};
+// --- end P6a ---

package/dist/core/backoff.d.ts

@@ -0,0 +1,20 @@
+import type { Duration } from './kernel.js';
+import { RetryPhase, TimerHold } from './constants.js';
+export interface BackoffTiming {
+    readonly backoffBase: Duration;
+    readonly backoffCap: Duration;
+}
+export declare class Backoff {
+    private readonly timing;
+    private readonly hold;
+    private failures;
+    private retry;
+    private proven;
+    constructor(timing: BackoffTiming, hold: TimerHold);
+    get phase(): RetryPhase;
+    schedule(run: () => void): void;
+    survive(): void;
+    stop(): void;
+    private timer;
+    private clear;
+}

package/dist/core/backoff.js

@@ -0,0 +1,53 @@
+// Role: the capped exponential backoff of the core link and events.
+// Informs HERDR-ADR-0020 (the herdr-core client); ported from the desktop work in herdr-plugins.
+import { must } from './kernel.js';
+import { parseCount } from './kernel.js';
+import { RetryPhase, TimerHold } from './constants.js';
+import { nextBackoff } from './wire.js';
+const ZERO = must(parseCount(0));
+const ONE = must(parseCount(1));
+const HOLD = {
+    [TimerHold.HoldsProcess]: () => undefined,
+    [TimerHold.LetsProcessEnd]: (timer) => { timer.unref(); },
+};
+export class Backoff {
+    timing;
+    hold;
+    failures = ZERO;
+    retry = null;
+    proven = null;
+    constructor(timing, hold) {
+        this.timing = timing;
+        this.hold = hold;
+    }
+    get phase() {
+        return this.retry === null ? RetryPhase.Idle : RetryPhase.Waiting;
+    }
+    schedule(run) {
+        this.stop();
+        const delay = nextBackoff(this.failures, this.timing.backoffBase, this.timing.backoffCap);
+        this.failures = must(parseCount(this.failures + ONE));
+        this.retry = this.timer(() => { this.retry = null; run(); }, delay);
+    }
+    survive() {
+        this.clear(this.proven);
+        this.proven = setTimeout(() => { this.proven = null; this.failures = ZERO; }, this.timing.backoffCap);
+        this.proven.unref();
+    }
+    stop() {
+        this.clear(this.retry);
+        this.clear(this.proven);
+        this.retry = null;
+        this.proven = null;
+    }
+    timer(run, delay) {
+        const timer = setTimeout(run, delay);
+        HOLD[this.hold](timer);
+        return timer;
+    }
+    clear(timer) {
+        if (timer !== null) {
+            clearTimeout(timer);
+        }
+    }
+}

package/dist/core/constants.d.ts

@@ -0,0 +1,143 @@
+import type { Count, Duration, NonEmptyText, Text } from './kernel.js';
+export declare const HC_SOCKET_ENV: NonEmptyText;
+export declare const HC_RUNTIME_ENV: NonEmptyText;
+export declare const HC_SESSION_ENV: NonEmptyText;
+export declare const HC_DEFAULT_SESSION: NonEmptyText;
+export declare const HC_SOCKET_FOLDER: NonEmptyText;
+export declare const HC_RUN_ROOT: NonEmptyText;
+export declare const HC_SOCKET_SUFFIX: NonEmptyText;
+export declare const HC_GENERATION: Count;
+export declare const HC_HELLO_METHOD: NonEmptyText;
+export declare const HC_SUBSCRIBE_METHOD: NonEmptyText;
+export declare const HC_LIST_METHOD: NonEmptyText;
+export declare const HC_GET_METHOD: NonEmptyText;
+export declare const HC_READ_METHOD: NonEmptyText;
+export declare const HC_HELLO_TIMEOUT: Duration;
+export declare const HC_BACKOFF_BASE: Duration;
+export declare const HC_BACKOFF_CAP: Duration;
+export declare const HC_BACKOFF_MAX_DOUBLINGS = 20;
+export declare const HC_HEARTBEAT_EVERY: Duration;
+export declare const HC_HEARTBEAT_MISSES: Count;
+export declare const HC_CALL_TIMEOUT: Duration;
+export declare const HC_LINE_CAP: Count;
+export declare const HC_JSONRPC_VERSION = "2.0";
+export declare const HC_LINE_SEPARATOR = "\n";
+export declare const EMPTY_TEXT: Text;
+export declare const UTF8 = "utf8";
+export declare const FIRST_CALL_ID = 1;
+export declare const CoreText: {
+    readonly NoConnection: Text;
+    readonly Closed: Text;
+    readonly Dropped: Text;
+    readonly Down: Text;
+    readonly Connecting: Text;
+    readonly HelloUnreadable: Text;
+    readonly OddResult: Text;
+    readonly Generation: (generation: Count) => Text;
+    readonly Fault: (reason: Text, message: Text) => Text;
+    readonly Invariant: (detail: string) => string;
+};
+export declare const JsType: {
+    readonly Object: 'object';
+    readonly Number: 'number';
+    readonly String: 'string';
+};
+export declare const ResultKind: {
+    readonly Ok: 'ok';
+    readonly Err: 'err';
+};
+export type ResultKind = (typeof ResultKind)[keyof typeof ResultKind];
+export declare const ParseFailureKind: {
+    readonly NotAString: 'not-a-string';
+    readonly NotANumber: 'not-a-number';
+    readonly Empty: 'empty';
+    readonly NotAnInteger: 'not-an-integer';
+    readonly NotARow: 'not-a-row';
+    readonly OutOfRange: 'out-of-range';
+};
+export type ParseFailureKind = (typeof ParseFailureKind)[keyof typeof ParseFailureKind];
+export declare const CoreErrorName: {
+    readonly Invariant: 'CoreInvariantError';
+};
+export declare const UnknownWhy: {
+    readonly Timeout: 'timeout';
+    readonly Unreadable: 'unreadable';
+    readonly Unreachable: 'unreachable';
+    readonly NotFound: 'not-found';
+    readonly Failed: 'failed';
+};
+export type UnknownWhy = (typeof UnknownWhy)[keyof typeof UnknownWhy];
+export declare const OutcomeKind: {
+    readonly Answer: 'answer';
+    readonly Unknown: 'unknown';
+};
+export type OutcomeKind = (typeof OutcomeKind)[keyof typeof OutcomeKind];
+export declare const HcKind: {
+    readonly Reply: 'reply';
+    readonly Odd: 'odd';
+    readonly Fault: 'fault';
+    readonly Event: 'event';
+    readonly Heartbeat: 'heartbeat';
+    readonly Missed: 'missed';
+    readonly Snapshot: 'snapshot';
+};
+export type HcKind = (typeof HcKind)[keyof typeof HcKind];
+export declare const HcNotificationMethod: {
+    readonly Event: 'event';
+    readonly Heartbeat: 'heartbeat';
+    readonly Missed: 'missed';
+};
+export type HcNotificationMethod = (typeof HcNotificationMethod)[keyof typeof HcNotificationMethod];
+export declare const HcField: {
+    readonly JsonRpc: 'jsonrpc';
+    readonly Id: 'id';
+    readonly Method: 'method';
+    readonly Params: 'params';
+    readonly Result: 'result';
+    readonly Error: 'error';
+    readonly Seq: 'seq';
+    readonly Terminals: 'terminals';
+    readonly Terminal: 'terminal';
+    readonly Generation: 'generation';
+    readonly Version: 'version';
+    readonly Methods: 'methods';
+    readonly Code: 'code';
+    readonly Message: 'message';
+    readonly Data: 'data';
+    readonly Kind: 'kind';
+    readonly Type: 'type';
+};
+export declare const LinkState: {
+    readonly Idle: 'idle';
+    readonly Connecting: 'connecting';
+    readonly Ready: 'ready';
+    readonly Backoff: 'backoff';
+    readonly Closed: 'closed';
+};
+export type LinkState = (typeof LinkState)[keyof typeof LinkState];
+export declare const EventsPhase: {
+    readonly Waiting: 'waiting';
+    readonly Subscribed: 'subscribed';
+};
+export type EventsPhase = (typeof EventsPhase)[keyof typeof EventsPhase];
+export declare const Life: {
+    readonly Open: 'open';
+    readonly Closed: 'closed';
+};
+export type Life = (typeof Life)[keyof typeof Life];
+export declare const RetryPhase: {
+    readonly Idle: 'idle';
+    readonly Waiting: 'waiting';
+};
+export type RetryPhase = (typeof RetryPhase)[keyof typeof RetryPhase];
+export declare const TimerHold: {
+    readonly HoldsProcess: 'holds-process';
+    readonly LetsProcessEnd: 'lets-process-end';
+};
+export type TimerHold = (typeof TimerHold)[keyof typeof TimerHold];
+export declare const SocketEvent: {
+    readonly Data: 'data';
+    readonly Error: 'error';
+    readonly Close: 'close';
+    readonly Connect: 'connect';
+};

package/dist/core/constants.js

@@ -0,0 +1,98 @@
+export const HC_SOCKET_ENV = 'HC_SOCKET';
+export const HC_RUNTIME_ENV = 'XDG_RUNTIME_DIR';
+export const HC_SESSION_ENV = 'HC_SESSION';
+export const HC_DEFAULT_SESSION = 'default';
+export const HC_SOCKET_FOLDER = 'herdr-core';
+export const HC_RUN_ROOT = '/run/user';
+export const HC_SOCKET_SUFFIX = '.sock';
+export const HC_GENERATION = 1;
+export const HC_HELLO_METHOD = 'hello';
+export const HC_SUBSCRIBE_METHOD = 'events.subscribe';
+export const HC_LIST_METHOD = 'terminal.list';
+export const HC_GET_METHOD = 'terminal.get';
+export const HC_READ_METHOD = 'terminal.read';
+export const HC_HELLO_TIMEOUT = 5000;
+export const HC_BACKOFF_BASE = 500;
+export const HC_BACKOFF_CAP = 15_000;
+export const HC_BACKOFF_MAX_DOUBLINGS = 20;
+export const HC_HEARTBEAT_EVERY = 15_000;
+export const HC_HEARTBEAT_MISSES = 2;
+export const HC_CALL_TIMEOUT = 10_000;
+export const HC_LINE_CAP = 33_554_432;
+export const HC_JSONRPC_VERSION = '2.0';
+export const HC_LINE_SEPARATOR = '\n';
+export const EMPTY_TEXT = '';
+export const UTF8 = 'utf8';
+export const FIRST_CALL_ID = 1;
+// The messages the core client puts in an Unknown or an error.
+export const CoreText = {
+    NoConnection: 'no connection',
+    Closed: 'link closed',
+    Dropped: 'connection dropped',
+    Down: 'the core is down; reconnecting',
+    Connecting: 'connecting',
+    HelloUnreadable: 'hello reply',
+    OddResult: 'a result that is not an object',
+    Generation: (generation) => `generation ${generation}`,
+    Fault: (reason, message) => `${reason}: ${message}`,
+    Invariant: (detail) => `a load-time constant was refused: ${detail}`,
+};
+export const JsType = { Object: 'object', Number: 'number', String: 'string' };
+export const ResultKind = { Ok: 'ok', Err: 'err' };
+export const ParseFailureKind = {
+    NotAString: 'not-a-string',
+    NotANumber: 'not-a-number',
+    Empty: 'empty',
+    NotAnInteger: 'not-an-integer',
+    NotARow: 'not-a-row',
+    OutOfRange: 'out-of-range',
+};
+export const CoreErrorName = { Invariant: 'CoreInvariantError' };
+export const UnknownWhy = {
+    Timeout: 'timeout',
+    Unreadable: 'unreadable',
+    Unreachable: 'unreachable',
+    NotFound: 'not-found',
+    Failed: 'failed',
+};
+// What a call settled as: an answer from the core, or Unknown.
+export const OutcomeKind = { Answer: 'answer', Unknown: 'unknown' };
+// The kinds of a parsed message and of a feed item.
+export const HcKind = {
+    Reply: 'reply',
+    Odd: 'odd',
+    Fault: 'fault',
+    Event: 'event',
+    Heartbeat: 'heartbeat',
+    Missed: 'missed',
+    Snapshot: 'snapshot',
+};
+// The notification methods the core pushes on a subscription.
+export const HcNotificationMethod = { Event: 'event', Heartbeat: 'heartbeat', Missed: 'missed' };
+// The JSON fields of the core's wire.
+export const HcField = {
+    JsonRpc: 'jsonrpc',
+    Id: 'id',
+    Method: 'method',
+    Params: 'params',
+    Result: 'result',
+    Error: 'error',
+    Seq: 'seq',
+    Terminals: 'terminals',
+    Terminal: 'terminal',
+    Generation: 'generation',
+    Version: 'version',
+    Methods: 'methods',
+    Code: 'code',
+    Message: 'message',
+    Data: 'data',
+    Kind: 'kind',
+    Type: 'type',
+};
+export const LinkState = { Idle: 'idle', Connecting: 'connecting', Ready: 'ready', Backoff: 'backoff', Closed: 'closed' };
+export const EventsPhase = { Waiting: 'waiting', Subscribed: 'subscribed' };
+export const Life = { Open: 'open', Closed: 'closed' };
+export const RetryPhase = { Idle: 'idle', Waiting: 'waiting' };
+// Whether a retry timer keeps the process alive.
+export const TimerHold = { HoldsProcess: 'holds-process', LetsProcessEnd: 'lets-process-end' };
+export const SocketEvent = { Data: 'data', Error: 'error', Close: 'close', Connect: 'connect' };

package/dist/core/errors.d.ts

@@ -0,0 +1,35 @@
+import { OutcomeKind } from './constants.js';
+import type { ParseFailureKind, UnknownWhy } from './constants.js';
+import type { Duration } from './kernel.js';
+export type ParseFailure = {
+    readonly kind: ParseFailureKind;
+};
+export declare class CoreInvariantError extends Error {
+    readonly name: string;
+    constructor(detail: string);
+}
+export type Unknowable = {
+    readonly why: typeof UnknownWhy.Timeout;
+    readonly after: Duration;
+} | {
+    readonly why: typeof UnknownWhy.Unreadable;
+    readonly detail: string;
+} | {
+    readonly why: typeof UnknownWhy.Unreachable;
+    readonly detail: string;
+} | {
+    readonly why: typeof UnknownWhy.NotFound;
+    readonly what: string;
+} | {
+    readonly why: typeof UnknownWhy.Failed;
+    readonly code: number;
+    readonly detail: string;
+};
+export type Unknown = {
+    readonly kind: typeof OutcomeKind.Unknown;
+    readonly why: Unknowable;
+};
+export declare function unknown(why: Unknowable): Unknown;
+export declare function isUnknown<T extends {
+    readonly kind: string;
+}>(value: T | Unknown): value is Unknown;

package/dist/core/errors.js

@@ -0,0 +1,16 @@
+// Role: every failure of the herdr-core client ; its kinds live in constants.ts: Unknown (a call whose outcome cannot be known), ParseFailure (why a parser refused) and CoreInvariantError (a load-time constant refused, a bug).
+// Informs HERDR-ADR-0020; merged by HERDR-ADR-0021 from parse-failure.ts, unknown.ts.
+import { CoreErrorName, CoreText, OutcomeKind } from './constants.js';
+// A load-time constant failed its own parser: a bug in the SDK, never a runtime condition.
+export class CoreInvariantError extends Error {
+    name = CoreErrorName.Invariant;
+    constructor(detail) {
+        super(CoreText.Invariant(detail));
+    }
+}
+export function unknown(why) {
+    return { kind: OutcomeKind.Unknown, why };
+}
+export function isUnknown(value) {
+    return value.kind === OutcomeKind.Unknown;
+}