@openlimiter/core 0.2.0 → 1.2.0

package/dist/collection.d.ts

@@ -0,0 +1,151 @@
+import { snapshotIdentity } from "./merge.js";
+import type { ProviderCode, Snapshot } from "./types.js";
+/**
+ * What one collection run achieved, and what the cache does about it.
+ *
+ * The product's whole honesty problem in one file. A provider answering with a
+ * 200 is not a reading, and a provider answering with a well formed body whose
+ * meaning has changed is worse than a provider answering with nothing: the
+ * first is visibly unknown, the second is confidently wrong. So a run reports
+ * what it achieved rather than what it received, and drift is a first class
+ * outcome with a first class consequence.
+ *
+ * That consequence is a SUPPRESSION. Removing the affected rows is not enough
+ * on its own, because a cache is shared: the desktop, the command line tool,
+ * the adapters and the dashboard all read it, and any one of them could write a
+ * stale row back before the others noticed. A suppression is a standing
+ * instruction in the document itself, so every reader on the machine reaches
+ * the same unknown at the same instant, and a row that predates it can never
+ * become visible again.
+ *
+ * Everything here is pure: no clock, no file system, no network. The caller
+ * supplies the instant, so a whole history can be replayed and land on the same
+ * answer every time.
+ */
+/**
+ * Why a collection run produced nothing usable.
+ *
+ * `drift` is separated from every other reason on purpose, and is the only one
+ * that suppresses. The rest are ordinary interruptions: the provider was busy,
+ * the machine was offline, a credential lapsed. None of those say anything
+ * about whether the reading we already hold is still true, so none of them
+ * throws it away; the reading ages out through the ordinary freshness rule
+ * instead. Drift is the one that says the previous reading's MEANING is in
+ * doubt, and that cannot be waited out.
+ */
+export declare const COLLECTION_FAILURE_REASONS: readonly ["drift", "network", "authentication", "rate_limited", "remote_error", "local_io"];
+export type CollectionFailureReason = (typeof COLLECTION_FAILURE_REASONS)[number];
+export type CollectionReport = {
+    ok: true;
+    provider: ProviderCode;
+    accountId?: string;
+    observedAt: string;
+    snapshots: readonly Snapshot[];
+} | {
+    ok: false;
+    provider: ProviderCode;
+    accountId?: string;
+    observedAt: string;
+    reason: CollectionFailureReason;
+};
+/**
+ * A standing instruction to distrust one identity's cached rows.
+ *
+ * `reason` is a single literal rather than the full failure vocabulary,
+ * deliberately: drift is the only failure that suppresses, and a type that
+ * could hold "network" would invite a future caller to suppress on a dropped
+ * packet, which would throw away a perfectly good reading every time a train
+ * went into a tunnel.
+ */
+export interface CacheSuppression {
+    provider: ProviderCode;
+    accountId?: string;
+    reason: "drift";
+    suppressedAt: string;
+}
+/**
+ * How many suppressions one cache document may carry.
+ *
+ * The same order of magnitude as the row bound, because there is at most one
+ * suppression per identity and identities are what rows are keyed by. A
+ * document claiming more than this is not a cache with a lot of drift, it is a
+ * document somebody wrote by hand.
+ */
+export declare const MAX_CACHE_SUPPRESSIONS = 64;
+/** The cache as this module reasons about it: rows, and what to distrust. */
+export interface CacheState {
+    snapshots: readonly Snapshot[];
+    suppressions: readonly CacheSuppression[];
+}
+/**
+ * The one place provider and account identity is decided.
+ *
+ * A row, a report and a suppression all have to agree on what "the same thing"
+ * means, and the way that goes wrong is three near identical comparisons in
+ * three files, one of which forgets that an absent account is not the account
+ * called "default". So there is one function, everything calls it, and an
+ * absent account keys exactly as it always did.
+ */
+export declare function collectionIdentity(provider: ProviderCode, accountId?: string): string;
+/** Whether this snapshot belongs to this provider and account. */
+export declare function snapshotBelongsTo(snapshot: Snapshot, provider: ProviderCode, accountId?: string): boolean;
+/**
+ * A suppression document as read back from disk.
+ *
+ * `ok: false` is not "there were none". It means the suppression data could not
+ * be believed, and since a suppression is the only thing standing between a
+ * stale row and a surface, a suppression list that cannot be read makes every
+ * row in that document unknown. That is the fail closed direction: the cost of
+ * being wrong here is showing a number that is no longer true, and the cost of
+ * being right is one refresh cycle of honest unknown.
+ */
+export type SuppressionReadResult = {
+    ok: true;
+    suppressions: CacheSuppression[];
+} | {
+    ok: false;
+};
+/**
+ * Read the suppression list out of a cache document.
+ *
+ * Absent is the ordinary case and reads as an empty list: a document written
+ * before suppressions existed has none, which is true. Anything present and
+ * unreadable is refused whole rather than partially salvaged, because a
+ * half read suppression list would silently un suppress whichever entries
+ * failed to parse, which is exactly the value it exists to prevent.
+ */
+export declare function readSuppressions(value: unknown): SuppressionReadResult;
+/**
+ * Fold one collection report into the cache.
+ *
+ * Four rules, one per kind of outcome, and no fifth:
+ *
+ *   1. A successful report replaces every row for its identity and clears that
+ *      identity's suppression. A provider that has started making sense again
+ *      is trusted again, and only a real parse can say that.
+ *   2. A drift report removes those rows and records the suppression, replacing
+ *      any earlier one, so the instant always reflects the latest drift.
+ *   3. Every other failure changes nothing at all. The rows we hold stay, and
+ *      age out through the ordinary freshness rule.
+ *   4. A report whose instant cannot be read is not applied. An unreadable
+ *      instant cannot be compared with a row's observation, so it could neither
+ *      suppress honestly nor be cleared honestly.
+ */
+export declare function applyCollectionReport(state: CacheState, report: CollectionReport): CacheState;
+/**
+ * The rows a surface may actually see.
+ *
+ * A row survives only when nothing suppresses its identity, or when it was
+ * observed strictly AFTER the suppression that does. Strictly after, not at or
+ * after: a row observed in the same millisecond as the drift that suppressed it
+ * is the very row the drift was about.
+ *
+ * Every read goes through here, which is what makes drift instant everywhere.
+ * `buildAdvice` is handed the result of this function and never the raw rows,
+ * so a suppressed provider is reported unknown by the statusline, the agent
+ * context, the dashboard and the tray in the same tick.
+ */
+export declare function visibleSnapshots(state: CacheState): Snapshot[];
+/** Identity, exported for the cache writer that has to key rows the same way. */
+export { snapshotIdentity };
+//# sourceMappingURL=collection.d.ts.map

package/dist/collection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"collection.d.ts","sourceRoot":"","sources":["../src/collection.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkB,gBAAgB,EAAqB,MAAM,YAAY,CAAC;AACjF,OAAO,KAAK,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAGzD;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH;;;;;;;;;;GAUG;AACH,eAAO,MAAM,0BAA0B,6FAO7B,CAAC;AAEX,MAAM,MAAM,uBAAuB,GAAG,CAAC,OAAO,0BAA0B,CAAC,CAAC,MAAM,CAAC,CAAC;AAElF,MAAM,MAAM,gBAAgB,GACxB;IACE,EAAE,EAAE,IAAI,CAAC;IACT,QAAQ,EAAE,YAAY,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,SAAS,QAAQ,EAAE,CAAC;CAChC,GACD;IACE,EAAE,EAAE,KAAK,CAAC;IACV,QAAQ,EAAE,YAAY,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,uBAAuB,CAAC;CACjC,CAAC;AAEN;;;;;;;;GAQG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,YAAY,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,OAAO,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,sBAAsB,KAAoB,CAAC;AAExD,6EAA6E;AAC7E,MAAM,WAAW,UAAU;IACzB,SAAS,EAAE,SAAS,QAAQ,EAAE,CAAC;IAC/B,YAAY,EAAE,SAAS,gBAAgB,EAAE,CAAC;CAC3C;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,YAAY,EACtB,SAAS,CAAC,EAAE,MAAM,GACjB,MAAM,CAER;AAED,kEAAkE;AAClE,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,QAAQ,EAClB,QAAQ,EAAE,YAAY,EACtB,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAMT;AAWD;;;;;;;;;GASG;AACH,MAAM,MAAM,qBAAqB,GAC7B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,YAAY,EAAE,gBAAgB,EAAE,CAAA;CAAE,GAC9C;IAAE,EAAE,EAAE,KAAK,CAAA;CAAE,CAAC;AASlB;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,qBAAqB,CA2BtE;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,UAAU,EACjB,MAAM,EAAE,gBAAgB,GACvB,UAAU,CAqCZ;AAeD;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,UAAU,GAAG,QAAQ,EAAE,CAe9D;AAED,iFAAiF;AACjF,OAAO,EAAE,gBAAgB,EAAE,CAAC"}

package/dist/collection.js

@@ -0,0 +1,218 @@
+import { mergeSnapshots, snapshotIdentity, MAX_CACHE_ENTRIES } from "./merge.js";
+import { PROVIDER_CODES, ACCOUNT_ID_PATTERN } from "./types.js";
+/**
+ * What one collection run achieved, and what the cache does about it.
+ *
+ * The product's whole honesty problem in one file. A provider answering with a
+ * 200 is not a reading, and a provider answering with a well formed body whose
+ * meaning has changed is worse than a provider answering with nothing: the
+ * first is visibly unknown, the second is confidently wrong. So a run reports
+ * what it achieved rather than what it received, and drift is a first class
+ * outcome with a first class consequence.
+ *
+ * That consequence is a SUPPRESSION. Removing the affected rows is not enough
+ * on its own, because a cache is shared: the desktop, the command line tool,
+ * the adapters and the dashboard all read it, and any one of them could write a
+ * stale row back before the others noticed. A suppression is a standing
+ * instruction in the document itself, so every reader on the machine reaches
+ * the same unknown at the same instant, and a row that predates it can never
+ * become visible again.
+ *
+ * Everything here is pure: no clock, no file system, no network. The caller
+ * supplies the instant, so a whole history can be replayed and land on the same
+ * answer every time.
+ */
+/**
+ * Why a collection run produced nothing usable.
+ *
+ * `drift` is separated from every other reason on purpose, and is the only one
+ * that suppresses. The rest are ordinary interruptions: the provider was busy,
+ * the machine was offline, a credential lapsed. None of those say anything
+ * about whether the reading we already hold is still true, so none of them
+ * throws it away; the reading ages out through the ordinary freshness rule
+ * instead. Drift is the one that says the previous reading's MEANING is in
+ * doubt, and that cannot be waited out.
+ */
+export const COLLECTION_FAILURE_REASONS = [
+    "drift",
+    "network",
+    "authentication",
+    "rate_limited",
+    "remote_error",
+    "local_io"
+];
+/**
+ * How many suppressions one cache document may carry.
+ *
+ * The same order of magnitude as the row bound, because there is at most one
+ * suppression per identity and identities are what rows are keyed by. A
+ * document claiming more than this is not a cache with a lot of drift, it is a
+ * document somebody wrote by hand.
+ */
+export const MAX_CACHE_SUPPRESSIONS = MAX_CACHE_ENTRIES;
+/**
+ * The one place provider and account identity is decided.
+ *
+ * A row, a report and a suppression all have to agree on what "the same thing"
+ * means, and the way that goes wrong is three near identical comparisons in
+ * three files, one of which forgets that an absent account is not the account
+ * called "default". So there is one function, everything calls it, and an
+ * absent account keys exactly as it always did.
+ */
+export function collectionIdentity(provider, accountId) {
+    return accountId === undefined ? provider : provider + " " + accountId;
+}
+/** Whether this snapshot belongs to this provider and account. */
+export function snapshotBelongsTo(snapshot, provider, accountId) {
+    return (snapshot.provider === provider &&
+        collectionIdentity(provider, snapshot.accountId) ===
+            collectionIdentity(provider, accountId));
+}
+function parseInstant(value) {
+    const parsed = Date.parse(value);
+    return Number.isFinite(parsed) ? parsed : null;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isProviderCode(value) {
+    return (typeof value === "string" &&
+        PROVIDER_CODES.includes(value));
+}
+/**
+ * Read the suppression list out of a cache document.
+ *
+ * Absent is the ordinary case and reads as an empty list: a document written
+ * before suppressions existed has none, which is true. Anything present and
+ * unreadable is refused whole rather than partially salvaged, because a
+ * half read suppression list would silently un suppress whichever entries
+ * failed to parse, which is exactly the value it exists to prevent.
+ */
+export function readSuppressions(value) {
+    if (value === undefined || value === null)
+        return { ok: true, suppressions: [] };
+    if (!Array.isArray(value))
+        return { ok: false };
+    if (value.length > MAX_CACHE_SUPPRESSIONS)
+        return { ok: false };
+    const suppressions = [];
+    for (const entry of value) {
+        if (!isRecord(entry))
+            return { ok: false };
+        if (!isProviderCode(entry["provider"]))
+            return { ok: false };
+        if (entry["reason"] !== "drift")
+            return { ok: false };
+        const suppressedAt = entry["suppressedAt"];
+        if (typeof suppressedAt !== "string" || parseInstant(suppressedAt) === null) {
+            return { ok: false };
+        }
+        const accountId = entry["accountId"];
+        if (accountId !== undefined) {
+            if (typeof accountId !== "string" || !ACCOUNT_ID_PATTERN.test(accountId)) {
+                return { ok: false };
+            }
+        }
+        suppressions.push({
+            provider: entry["provider"],
+            reason: "drift",
+            suppressedAt,
+            ...(accountId === undefined ? {} : { accountId })
+        });
+    }
+    return { ok: true, suppressions };
+}
+/**
+ * Fold one collection report into the cache.
+ *
+ * Four rules, one per kind of outcome, and no fifth:
+ *
+ *   1. A successful report replaces every row for its identity and clears that
+ *      identity's suppression. A provider that has started making sense again
+ *      is trusted again, and only a real parse can say that.
+ *   2. A drift report removes those rows and records the suppression, replacing
+ *      any earlier one, so the instant always reflects the latest drift.
+ *   3. Every other failure changes nothing at all. The rows we hold stay, and
+ *      age out through the ordinary freshness rule.
+ *   4. A report whose instant cannot be read is not applied. An unreadable
+ *      instant cannot be compared with a row's observation, so it could neither
+ *      suppress honestly nor be cleared honestly.
+ */
+export function applyCollectionReport(state, report) {
+    if (parseInstant(report.observedAt) === null)
+        return state;
+    const belongs = (snapshot) => snapshotBelongsTo(snapshot, report.provider, report.accountId);
+    const suppressionMatches = (suppression) => suppression.provider === report.provider &&
+        collectionIdentity(report.provider, suppression.accountId) ===
+            collectionIdentity(report.provider, report.accountId);
+    if (report.ok) {
+        /* Rows for this identity are dropped before the merge rather than left for
+           it, because a successful run that returns FEWER meters than last time
+           must not leave the missing ones behind as fresh looking survivors. */
+        const kept = state.snapshots.filter((snapshot) => !belongs(snapshot));
+        return {
+            snapshots: mergeSnapshots(kept, report.snapshots),
+            suppressions: state.suppressions.filter((suppression) => !suppressionMatches(suppression))
+        };
+    }
+    if (report.reason !== "drift")
+        return state;
+    const suppression = {
+        provider: report.provider,
+        reason: "drift",
+        suppressedAt: report.observedAt,
+        ...(report.accountId === undefined ? {} : { accountId: report.accountId })
+    };
+    const others = state.suppressions.filter((existing) => !suppressionMatches(existing));
+    return {
+        snapshots: state.snapshots.filter((snapshot) => !belongs(snapshot)),
+        /* Bounded by dropping the oldest, so a machine that drifts on every
+           provider for a month cannot grow the document without limit. */
+        suppressions: boundSuppressions([...others, suppression])
+    };
+}
+function suppressedMilliseconds(suppression) {
+    return parseInstant(suppression.suppressedAt) ?? 0;
+}
+function boundSuppressions(suppressions) {
+    if (suppressions.length <= MAX_CACHE_SUPPRESSIONS)
+        return [...suppressions];
+    return [...suppressions]
+        .sort((left, right) => suppressedMilliseconds(right) - suppressedMilliseconds(left))
+        .slice(0, MAX_CACHE_SUPPRESSIONS);
+}
+/**
+ * The rows a surface may actually see.
+ *
+ * A row survives only when nothing suppresses its identity, or when it was
+ * observed strictly AFTER the suppression that does. Strictly after, not at or
+ * after: a row observed in the same millisecond as the drift that suppressed it
+ * is the very row the drift was about.
+ *
+ * Every read goes through here, which is what makes drift instant everywhere.
+ * `buildAdvice` is handed the result of this function and never the raw rows,
+ * so a suppressed provider is reported unknown by the statusline, the agent
+ * context, the dashboard and the tray in the same tick.
+ */
+export function visibleSnapshots(state) {
+    if (state.suppressions.length === 0)
+        return [...state.snapshots];
+    return state.snapshots.filter((snapshot) => {
+        const observed = parseInstant(snapshot.observedAt);
+        for (const suppression of state.suppressions) {
+            if (!snapshotBelongsTo(snapshot, suppression.provider, suppression.accountId)) {
+                continue;
+            }
+            /* A row whose own observation cannot be read cannot be proven newer than
+               the suppression, so it is not shown. */
+            if (observed === null)
+                return false;
+            if (observed <= suppressedMilliseconds(suppression))
+                return false;
+        }
+        return true;
+    });
+}
+/** Identity, exported for the cache writer that has to key rows the same way. */
+export { snapshotIdentity };
+//# sourceMappingURL=collection.js.map

package/dist/collection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"collection.js","sourceRoot":"","sources":["../src/collection.ts"],"names":[],"mappings":"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"}

package/dist/connection-state.d.ts

@@ -0,0 +1,229 @@
+/**
+ * The connection lifecycle, as one pure function and two human tables.
+ *
+ * A parser is not a connection. The product's central honesty problem is that
+ * an implemented parser has been able to look like a live account, so the state
+ * a connection is in has to be a value the whole product agrees on rather than
+ * a sentence each surface invents. Everything here is data and arithmetic: no
+ * clock, no network, no storage, so a surface can replay a connection's whole
+ * history and get the same answer every time.
+ */
+export declare const CONNECTION_STATES: readonly ["NOT_CONFIGURED", "DETECTED", "NEEDS_AUTH", "READY_TO_ENABLE", "CONNECTING", "CONNECTED", "DEGRADED", "STALE", "AUTH_EXPIRED", "IMPORT_ONLY", "MANUAL", "UNSUPPORTED", "ERROR"];
+export type ConnectionState = (typeof CONNECTION_STATES)[number];
+/**
+ * How many consecutive network failures turn a degraded connection into a
+ * broken one. One timeout is a bad moment; three in a row is a fault worth
+ * showing a person.
+ */
+export declare const NETWORK_FAILURE_ERROR_THRESHOLD = 3;
+export type ConnectionEvent = 
+/** A supported local tool was found on this machine. */
+{
+    kind: "detected";
+}
+/** Setup established that this connection cannot proceed without a secret. */
+ | {
+    kind: "credential_required";
+}
+/** A secret was accepted into the operating system credential store. */
+ | {
+    kind: "credential_stored";
+}
+/** The user asked for this connection to start collecting. */
+ | {
+    kind: "enable_requested";
+}
+/** A remote read finished. `parsed` says whether we understood the body. */
+ | {
+    kind: "http_response";
+    status: number;
+    parsed: boolean;
+}
+/** A local read finished, for readers that never speak HTTP. */
+ | {
+    kind: "local_read";
+    parsed: boolean;
+}
+/** A read never reached the provider. `consecutive` counts failures in a row. */
+ | {
+    kind: "network_failure";
+    consecutive: number;
+}
+/** The newest observation aged past its own expiry. */
+ | {
+    kind: "expiry_passed";
+}
+/** The user removed this connection. */
+ | {
+    kind: "disconnected";
+}
+/** The product states this source can only be fed by an explicit import. */
+ | {
+    kind: "declared_import_only";
+}
+/** The product states this source is a user maintained plan. */
+ | {
+    kind: "declared_manual";
+}
+/** The product states no safe automatic source exists for this product. */
+ | {
+    kind: "declared_unsupported";
+};
+/**
+ * What the transition function cannot work out from the current state alone.
+ *
+ * The one authentication question is whether this connection has ever worked,
+ * and the current state cannot answer it. CONNECTED then a 404 lands in ERROR,
+ * and a 401 arriving there would read as "we never had a credential" when what
+ * actually happened is that a credential which used to work stopped, which is a
+ * different sentence and a different button. So the fact is carried on the
+ * connection record, where it belongs, and passed in. It is one way: nothing
+ * ever sets it back to false, because a connection that worked once always did.
+ */
+export interface ConnectionContext {
+    everConnected: boolean;
+}
+/**
+ * Advance a connection by one event.
+ *
+ * Total and pure: every state, event and context triple has an answer, and an
+ * event that makes no sense where it arrived leaves the state exactly as it was
+ * rather than inventing a transition. The context is required rather than
+ * defaulted, because a caller that forgets it would silently get the wrong
+ * authentication answer, and a compiler error is cheaper than that.
+ */
+export declare function nextConnectionState(state: ConnectionState, event: ConnectionEvent, context: ConnectionContext): ConnectionState;
+/** One sentence per state, written for a person rather than for a log. */
+export declare const connectionSentence: {
+    readonly NOT_CONFIGURED: "Not connected.";
+    readonly DETECTED: "Found on this machine but not collecting yet.";
+    readonly NEEDS_AUTH: "Waiting for a credential.";
+    readonly READY_TO_ENABLE: "Ready to start collecting.";
+    readonly CONNECTING: "Connecting.";
+    readonly CONNECTED: "Connected and collecting.";
+    readonly DEGRADED: "The provider is refusing reads for now.";
+    readonly STALE: "The last reading is older than it should be.";
+    readonly AUTH_EXPIRED: "The stored credential stopped working.";
+    readonly IMPORT_ONLY: "Reads only what you import. Nothing is collected automatically.";
+    readonly MANUAL: "Shows the plan you entered yourself.";
+    readonly UNSUPPORTED: "No safe automatic source exists for this product yet.";
+    readonly ERROR: "This connection failed and needs a look.";
+};
+/** The one thing to do next, in the words of the button that does it. */
+export declare const connectionNextAction: {
+    readonly NOT_CONFIGURED: "Connect";
+    readonly DETECTED: "Enable local integration";
+    readonly NEEDS_AUTH: "Add credential";
+    readonly READY_TO_ENABLE: "Enable";
+    readonly CONNECTING: "Wait";
+    readonly CONNECTED: "Refresh now";
+    readonly DEGRADED: "Wait for the next retry";
+    readonly STALE: "Refresh now";
+    readonly AUTH_EXPIRED: "Reconnect";
+    readonly IMPORT_ONLY: "Import a payload";
+    readonly MANUAL: "Edit plan";
+    readonly UNSUPPORTED: "Add manual plan";
+    readonly ERROR: "View diagnostics";
+};
+/**
+ * Why a connection is not simply working, in a closed vocabulary.
+ *
+ * A state says WHAT a connection is. A reason says why it got there, and it is
+ * the half a person actually needs: "stale" is a shrug, "stale because the
+ * stored credential stopped working" is something they can act on. Closed
+ * rather than free text, because a reason is rendered next to a button and a
+ * provider must never be able to write either one.
+ */
+export declare const CONNECTION_REASONS: readonly ["token_expired", "reading_expired", "tool_not_running", "provider_refusing", "shape_mismatch", "network_unreachable", "no_credential"];
+export type ConnectionReason = (typeof CONNECTION_REASONS)[number];
+/** One sentence per reason, written for a person rather than for a log. */
+export declare const connectionReasonSentence: {
+    readonly token_expired: "The credential this connection uses stopped working.";
+    readonly reading_expired: "The newest reading is older than the window it describes.";
+    readonly tool_not_running: "The local tool has not written a reading yet.";
+    readonly provider_refusing: "The provider refused the last read.";
+    readonly shape_mismatch: "The answer did not match the shape this build reads.";
+    readonly network_unreachable: "The last read never reached the provider.";
+    readonly no_credential: "No credential has been stored for this connection.";
+};
+/**
+ * The connection as one value a surface can render without deciding anything.
+ *
+ * State, reason, and the one instruction that belongs to that pair. Every field
+ * is written by OpenLimiter and never by a provider, which is what keeps a
+ * payload from writing the sentence beside a button.
+ */
+export interface ConnectionStatus {
+    readonly state: ConnectionState;
+    readonly reason: ConnectionReason | null;
+    /** What the PERSON does next. Never something this app does on their behalf. */
+    readonly instruction: string;
+}
+/**
+ * The local tool a connection reads through, when one exists.
+ *
+ * Carried so an instruction can name it. A connection with no local tool, such
+ * as a remote read behind a key the person pasted, passes null and gets an
+ * instruction that names no tool rather than an invented one.
+ */
+export type ConnectionTool = string | null;
+/**
+ * One connection status, from a state and an optional reason.
+ *
+ * Pure, total, and the only place an instruction is chosen. A reason wins the
+ * instruction whenever it has one, because it is the more specific fact; with
+ * no reason the state's own next action stands. Nothing here reads a clock, a
+ * network or a disk, so a surface and a test see the same answer.
+ */
+export declare function connectionStatus(state: ConnectionState, reason?: ConnectionReason | null, tool?: ConnectionTool): ConnectionStatus;
+/** The seven providers on the Connect and See catalogue surface. */
+export declare const CATALOGUE_PROVIDER_IDS: readonly ["claude", "openrouter", "codex", "antigravity", "opencode", "grok", "kimi"];
+export type CatalogueProviderId = (typeof CATALOGUE_PROVIDER_IDS)[number];
+export type CataloguePlatform = "windows" | "macos" | "linux";
+export type CatalogueCapabilityMode = "automatic" | "manual" | "event_driven";
+export type CatalogueCapabilityMaturity = "supported" | "experimental";
+export type CatalogueCapabilityLabel = "Supported" | "Event driven" | "Experimental" | "Manual" | "Manual experimental";
+export type CatalogueAuthMode = "existing_local_cli" | "api_key" | "manual";
+export interface CataloguePlatformCapability {
+    mode: CatalogueCapabilityMode;
+    maturity: CatalogueCapabilityMaturity;
+    label: CatalogueCapabilityLabel;
+}
+export interface ProviderCatalogueEntry {
+    providerId: CatalogueProviderId;
+    displayName: string;
+    connectionState: ConnectionState;
+    capabilities: Readonly<Record<CataloguePlatform, CataloguePlatformCapability>>;
+    authMode: CatalogueAuthMode;
+    action: string;
+}
+export interface GeneratedProviderDocument {
+    providers?: unknown;
+}
+/**
+ * Join generated provider facts to the closed connection state model.
+ *
+ * The generated document supplies identity, display name, auth mode and the
+ * platform set. Product capability maturity is the frozen overlay above. No
+ * site or local application is inspected at runtime.
+ */
+export declare function queryProviderCatalogue(generated: GeneratedProviderDocument, states?: Readonly<Partial<Record<CatalogueProviderId, ConnectionState>>>): readonly ProviderCatalogueEntry[];
+export interface PlannedProviderEntry {
+    specId: string;
+    displayName: string;
+    action: "Planned";
+}
+export type CatalogueRow = ({
+    availability: "connectable";
+} & ProviderCatalogueEntry) | ({
+    availability: "planned";
+} & PlannedProviderEntry);
+/**
+ * The connections surface showing connectable providers and planned products.
+ *
+ * The product catalogue presents every supported or planned provider in document
+ * order after the connectable set. Planned rows carry no connection state because
+ * no background collector or credential exists for them.
+ */
+export declare function queryCatalogueRows(generated: GeneratedProviderDocument, states?: Readonly<Partial<Record<CatalogueProviderId, ConnectionState>>>): readonly CatalogueRow[];
+//# sourceMappingURL=connection-state.d.ts.map

package/dist/connection-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection-state.d.ts","sourceRoot":"","sources":["../src/connection-state.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,eAAO,MAAM,iBAAiB,2LAcpB,CAAC;AAEX,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,iBAAiB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEjE;;;;GAIG;AACH,eAAO,MAAM,+BAA+B,IAAI,CAAC;AAEjD,MAAM,MAAM,eAAe;AACzB,wDAAwD;AACtD;IAAE,IAAI,EAAE,UAAU,CAAA;CAAE;AACtB,8EAA8E;GAC5E;IAAE,IAAI,EAAE,qBAAqB,CAAA;CAAE;AACjC,wEAAwE;GACtE;IAAE,IAAI,EAAE,mBAAmB,CAAA;CAAE;AAC/B,8DAA8D;GAC5D;IAAE,IAAI,EAAE,kBAAkB,CAAA;CAAE;AAC9B,4EAA4E;GAC1E;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,OAAO,CAAA;CAAE;AAC5D,gEAAgE;GAC9D;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,MAAM,EAAE,OAAO,CAAA;CAAE;AACzC,iFAAiF;GAC/E;IAAE,IAAI,EAAE,iBAAiB,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE;AAClD,uDAAuD;GACrD;IAAE,IAAI,EAAE,eAAe,CAAA;CAAE;AAC3B,wCAAwC;GACtC;IAAE,IAAI,EAAE,cAAc,CAAA;CAAE;AAC1B,4EAA4E;GAC1E;IAAE,IAAI,EAAE,sBAAsB,CAAA;CAAE;AAClC,gEAAgE;GAC9D;IAAE,IAAI,EAAE,iBAAiB,CAAA;CAAE;AAC7B,2EAA2E;GACzE;IAAE,IAAI,EAAE,sBAAsB,CAAA;CAAE,CAAC;AAcrC;;;;;;;;;;GAUG;AACH,MAAM,WAAW,iBAAiB;IAChC,aAAa,EAAE,OAAO,CAAC;CACxB;AAuBD;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,eAAe,EACtB,KAAK,EAAE,eAAe,EACtB,OAAO,EAAE,iBAAiB,GACzB,eAAe,CAuDjB;AAED,0EAA0E;AAC1E,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;CAcqB,CAAC;AAErD,yEAAyE;AACzE,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;CAcmB,CAAC;AAErD;;;;;;;;GAQG;AACH,eAAO,MAAM,kBAAkB,kJAQrB,CAAC;AAEX,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEnE,2EAA2E;AAC3E,eAAO,MAAM,wBAAwB;;;;;;;;CAQgB,CAAC;AAEtD;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,KAAK,EAAE,eAAe,CAAC;IAChC,QAAQ,CAAC,MAAM,EAAE,gBAAgB,GAAG,IAAI,CAAC;IACzC,gFAAgF;IAChF,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED;;;;;;GAMG;AACH,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,IAAI,CAAC;AA2C3C;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,eAAe,EACtB,MAAM,GAAE,gBAAgB,GAAG,IAAW,EACtC,IAAI,GAAE,cAAqB,GAC1B,gBAAgB,CAOlB;AAED,oEAAoE;AACpE,eAAO,MAAM,sBAAsB,uFAQzB,CAAC;AAEX,MAAM,MAAM,mBAAmB,GAAG,CAAC,OAAO,sBAAsB,CAAC,CAAC,MAAM,CAAC,CAAC;AAC1E,MAAM,MAAM,iBAAiB,GAAG,SAAS,GAAG,OAAO,GAAG,OAAO,CAAC;AAC9D,MAAM,MAAM,uBAAuB,GAAG,WAAW,GAAG,QAAQ,GAAG,cAAc,CAAC;AAC9E,MAAM,MAAM,2BAA2B,GAAG,WAAW,GAAG,cAAc,CAAC;AACvE,MAAM,MAAM,wBAAwB,GAChC,WAAW,GACX,cAAc,GACd,cAAc,GACd,QAAQ,GACR,qBAAqB,CAAC;AAC1B,MAAM,MAAM,iBAAiB,GAAG,oBAAoB,GAAG,SAAS,GAAG,QAAQ,CAAC;AAE5E,MAAM,WAAW,2BAA2B;IAC1C,IAAI,EAAE,uBAAuB,CAAC;IAC9B,QAAQ,EAAE,2BAA2B,CAAC;IACtC,KAAK,EAAE,wBAAwB,CAAC;CACjC;AAED,MAAM,WAAW,sBAAsB;IACrC,UAAU,EAAE,mBAAmB,CAAC;IAChC,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,EAAE,eAAe,CAAC;IACjC,YAAY,EAAE,QAAQ,CAAC,MAAM,CAAC,iBAAiB,EAAE,2BAA2B,CAAC,CAAC,CAAC;IAC/E,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,MAAM,EAAE,MAAM,CAAC;CAChB;AAUD,MAAM,WAAW,yBAAyB;IACxC,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAyED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,SAAS,EAAE,yBAAyB,EACpC,MAAM,GAAE,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,mBAAmB,EAAE,eAAe,CAAC,CAAC,CAAM,GAC3E,SAAS,sBAAsB,EAAE,CA+BnC;AAED,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,SAAS,CAAC;CACnB;AAED,MAAM,MAAM,YAAY,GACpB,CAAC;IAAE,YAAY,EAAE,aAAa,CAAA;CAAE,GAAG,sBAAsB,CAAC,GAC1D,CAAC;IAAE,YAAY,EAAE,SAAS,CAAA;CAAE,GAAG,oBAAoB,CAAC,CAAC;AAEzD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,yBAAyB,EACpC,MAAM,GAAE,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,mBAAmB,EAAE,eAAe,CAAC,CAAC,CAAM,GAC3E,SAAS,YAAY,EAAE,CA4BzB"}