@centient/secrets 0.10.0 → 0.11.0

package/dist/cli/messages.js

@@ -1,14 +1,40 @@
 /**
- * Auth Module - Centralized Message Strings
+ * Auth CLI message catalog — the shared strings for the credential lifecycle a
+ * consuming CLI drives on top of this vault (`login`, `logout`, `auth status`,
+ * `auth refresh`, device flow, api-key entry).
  *
- * All user-visible strings for the auth module are defined here.
- * This module is i18n-ready: message values do not contain interpolated
- * strings — template functions accept parameters and return formatted strings.
+ * Scope (#217 C6-34). The previous header claimed "all user-visible strings for
+ * the auth module", which was never true of this package — there is no auth
+ * module here, and only one entry had an in-package call site. The verified
+ * scope is:
+ *
+ *   - IN — the auth/device-flow/token lifecycle listed above, driven by the
+ *     consuming CLI, plus the one credential-storage warning this package
+ *     itself emits: `warning.envVaultNoStorage`, from `EnvVault.store()` in
+ *     `../vault/vault-env.ts`.
+ *   - OUT — the `centient secrets …` operator CLI in `./secrets-cli.ts` and the
+ *     `[secrets] …` vault diagnostics under `../vault/`. Those are
+ *     command-specific and carry their own next-step lines; funnelling them
+ *     through a flat catalog would drop that specificity, so they are
+ *     deliberately not catalog entries.
+ *
+ * This catalog is part of the package's public surface — import it, do not copy
+ * it. It is exported precisely so a consuming CLI stops maintaining a fork:
+ * before #217, `centient` carried a byte-identical copy at
+ * `packages/centient/src/auth/messages.ts` that had already drifted on
+ * `warning.envVaultNoStorage` (the single entry this package consumes, and so
+ * the single entry that had been updated here).
+ *
+ * i18n-ready: no message value interpolates at the call site. Parameterized
+ * messages are template functions that take their parameters and return the
+ * finished string, so a translation layer can replace the catalog wholesale.
  *
  * Usage:
- *   import { AUTH_MESSAGES } from './messages.js';
- *   process.stderr.write(AUTH_MESSAGES.error.vaultWriteFailed + '\n');
- *   process.stderr.write(AUTH_MESSAGES.info.loginPrompt('https://auth.example.com') + '\n');
+ *   import { AUTH_MESSAGES } from "@centient/secrets";
+ *   process.stderr.write(AUTH_MESSAGES.error.vaultWriteFailed + "\n");
+ *   process.stderr.write(
+ *     AUTH_MESSAGES.info.loginPrompt("https://auth.example.com") + "\n",
+ *   );
  */
 // =============================================================================
 // Message catalog
@@ -45,7 +71,7 @@ export const AUTH_MESSAGES = {
         revokeNetworkFailure: "Could not reach server to revoke token — local credentials have been removed.",
         noCredentialsFound: "No stored credentials found. Run `centient login` to authenticate.",
         sessionExpiredIdle: "Session expired due to inactivity.",
-        envVaultNoStorage: "No secure credential storage available. Install libsecret (Linux: apt install libsecret-tools) or GPG for persistent storage. Using ENGRAM_API_KEY environment variable only.",
+        envVaultNoStorage: "No secure credential storage available. Install libsecret (Linux: apt install libsecret-tools) or GPG for persistent storage. The environment fallback is read-only; set ENGRAM_API_KEY for auth-token or the key's CENTIENT_SECRET_* variable.",
     },
     info: {
         loginPrompt: (verificationUri) => `Visit the following URL to authorize this device:\n  ${verificationUri}`,

package/dist/cli/messages.js.map

@@ -1 +1 @@
-{"version":3,"file":"messages.js","sourceRoot":"","sources":["../../src/cli/messages.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,gFAAgF;AAChF,kBAAkB;AAClB,gFAAgF;AAEhF,MAAM,CAAC,MAAM,aAAa,GAAG;IAC3B,OAAO,EAAE;QACP,QAAQ,EAAE,mDAAmD;QAC7D,SAAS,EAAE,+CAA+C;QAC1D,WAAW,EAAE,iCAAiC;QAC9C,cAAc,EAAE,+BAA+B;QAC/C,YAAY,EAAE,mCAAmC;QACjD,cAAc,EAAE,0BAA0B;KAC3C;IAED,KAAK,EAAE;QACL,gBAAgB,EAAE,uCAAuC;QACzD,eAAe,EAAE,wCAAwC;QACzD,iBAAiB,EAAE,0CAA0C;QAC7D,gBAAgB,EAAE,mCAAmC;QACrD,iBAAiB,EAAE,mDAAmD;QACtE,sBAAsB,EAAE,4CAA4C;QACpE,iBAAiB,EAAE,8CAA8C;QACjE,YAAY,EAAE,wDAAwD;QACtE,YAAY,EAAE,uBAAuB;QACrC,cAAc,EAAE,6CAA6C;QAC7D,YAAY,EAAE,sCAAsC;QACpD,aAAa,EAAE,0DAA0D;QACzE,YAAY,EAAE,sDAAsD;QACpE,mBAAmB,EAAE,CAAC,GAAW,EAAU,EAAE,CAC3C,4BAA4B,GAAG,qCAAqC;QACtE,uBAAuB,EACrB,sDAAsD;QACxD,iBAAiB,EAAE,CAAC,GAAW,EAAU,EAAE,CACzC,wBAAwB,GAAG,4CAA4C;KAC1E;IAED,OAAO,EAAE;QACP,iBAAiB,EAAE,CAAC,OAAe,EAAU,EAAE,CAC7C,yBAAyB,OAAO,UAAU,OAAO,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,sCAAsC;QAC1G,oBAAoB,EAClB,+EAA+E;QACjF,kBAAkB,EAChB,oEAAoE;QACtE,kBAAkB,EAAE,oCAAoC;QACxD,iBAAiB,EACf,+KAA+K;KAClL;IAED,IAAI,EAAE;QACJ,WAAW,EAAE,CAAC,eAAuB,EAAU,EAAE,CAC/C,wDAAwD,eAAe,EAAE;QAC3E,eAAe,EAAE,CAAC,QAAgB,EAAU,EAAE,CAC5C,qCAAqC,QAAQ,EAAE;QACjD,WAAW,EAAE,CAAC,OAAe,EAAU,EAAE,CACvC,iCAAiC,OAAO,cAAc;QACxD,iBAAiB,EACf,+EAA+E;QACjF,uBAAuB,EAAE,CAAC,SAAiB,EAAU,EAAE,CACrD,mCAAmC,SAAS,GAAG;QACjD,yBAAyB,EAAE,0CAA0C;QACrE,sBAAsB,EAAE,CAAC,OAAe,EAAU,EAAE,CAClD,8BAA8B,OAAO,UAAU,OAAO,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,IAAI;QAC7E,SAAS,EAAE,CAAC,SAAiB,EAAU,EAAE,CAAC,UAAU,SAAS,EAAE;QAC/D,cAAc,EAAE,gBAAgB;QAChC,aAAa,EAAE,uCAAuC;KACvD;CACO,CAAC"}
+{"version":3,"file":"messages.js","sourceRoot":"","sources":["../../src/cli/messages.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,gFAAgF;AAChF,kBAAkB;AAClB,gFAAgF;AAEhF,MAAM,CAAC,MAAM,aAAa,GAAG;IAC3B,OAAO,EAAE;QACP,QAAQ,EAAE,mDAAmD;QAC7D,SAAS,EAAE,+CAA+C;QAC1D,WAAW,EAAE,iCAAiC;QAC9C,cAAc,EAAE,+BAA+B;QAC/C,YAAY,EAAE,mCAAmC;QACjD,cAAc,EAAE,0BAA0B;KAC3C;IAED,KAAK,EAAE;QACL,gBAAgB,EAAE,uCAAuC;QACzD,eAAe,EAAE,wCAAwC;QACzD,iBAAiB,EAAE,0CAA0C;QAC7D,gBAAgB,EAAE,mCAAmC;QACrD,iBAAiB,EAAE,mDAAmD;QACtE,sBAAsB,EAAE,4CAA4C;QACpE,iBAAiB,EAAE,8CAA8C;QACjE,YAAY,EAAE,wDAAwD;QACtE,YAAY,EAAE,uBAAuB;QACrC,cAAc,EAAE,6CAA6C;QAC7D,YAAY,EAAE,sCAAsC;QACpD,aAAa,EAAE,0DAA0D;QACzE,YAAY,EAAE,sDAAsD;QACpE,mBAAmB,EAAE,CAAC,GAAW,EAAU,EAAE,CAC3C,4BAA4B,GAAG,qCAAqC;QACtE,uBAAuB,EACrB,sDAAsD;QACxD,iBAAiB,EAAE,CAAC,GAAW,EAAU,EAAE,CACzC,wBAAwB,GAAG,4CAA4C;KAC1E;IAED,OAAO,EAAE;QACP,iBAAiB,EAAE,CAAC,OAAe,EAAU,EAAE,CAC7C,yBAAyB,OAAO,UAAU,OAAO,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,sCAAsC;QAC1G,oBAAoB,EAClB,+EAA+E;QACjF,kBAAkB,EAChB,oEAAoE;QACtE,kBAAkB,EAAE,oCAAoC;QACxD,iBAAiB,EACf,iPAAiP;KACpP;IAED,IAAI,EAAE;QACJ,WAAW,EAAE,CAAC,eAAuB,EAAU,EAAE,CAC/C,wDAAwD,eAAe,EAAE;QAC3E,eAAe,EAAE,CAAC,QAAgB,EAAU,EAAE,CAC5C,qCAAqC,QAAQ,EAAE;QACjD,WAAW,EAAE,CAAC,OAAe,EAAU,EAAE,CACvC,iCAAiC,OAAO,cAAc;QACxD,iBAAiB,EACf,+EAA+E;QACjF,uBAAuB,EAAE,CAAC,SAAiB,EAAU,EAAE,CACrD,mCAAmC,SAAS,GAAG;QACjD,yBAAyB,EAAE,0CAA0C;QACrE,sBAAsB,EAAE,CAAC,OAAe,EAAU,EAAE,CAClD,8BAA8B,OAAO,UAAU,OAAO,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,IAAI;QAC7E,SAAS,EAAE,CAAC,SAAiB,EAAU,EAAE,CAAC,UAAU,SAAS,EAAE;QAC/D,cAAc,EAAE,gBAAgB;QAChC,aAAa,EAAE,uCAAuC;KACvD;CACO,CAAC"}

package/dist/client.d.ts

@@ -0,0 +1,26 @@
+import { type PolicyRunner, type SecretsOperationContext, type SecretsPolicy } from "./vault/policy.js";
+import type { SecretsProvider } from "./vault/types.js";
+export interface CreateSecretsClientOptions {
+    /** Credential-value storage provider used by this client only. */
+    readonly provider: SecretsProvider;
+    /** Policy membership is snapshotted at construction for this client. */
+    readonly policies?: readonly SecretsPolicy[];
+    /** Honest event identity when a legacy provider has no `name`. */
+    readonly providerName?: string;
+}
+export interface SecretsClient {
+    readonly providerName: string;
+    storeCredential(key: string, value: string, context?: SecretsOperationContext): Promise<boolean>;
+    getCredential(key: string, context?: SecretsOperationContext): Promise<string | null>;
+    deleteCredential(key: string, context?: SecretsOperationContext): Promise<boolean>;
+    listCredentials(prefix?: string, context?: SecretsOperationContext): Promise<string[]>;
+    isSessionValid(): boolean;
+}
+type InternalSecretsClientOptions = Omit<CreateSecretsClientOptions, "policies"> & {
+    readonly policyRunner: PolicyRunner;
+};
+export declare function createSecretsClient(options: CreateSecretsClientOptions): SecretsClient;
+/** @internal Legacy default-client construction seam. */
+export declare function createSecretsClientWithPolicyRunner(options: InternalSecretsClientOptions): SecretsClient;
+export {};
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,YAAY,EAKjB,KAAK,uBAAuB,EAC5B,KAAK,aAAa,EACnB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAOxD,MAAM,WAAW,0BAA0B;IACzC,kEAAkE;IAClE,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAC;IACnC,wEAAwE;IACxE,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,aAAa,EAAE,CAAC;IAC7C,kEAAkE;IAClE,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAChC;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,eAAe,CACb,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,uBAAuB,GAChC,OAAO,CAAC,OAAO,CAAC,CAAC;IACpB,aAAa,CACX,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,uBAAuB,GAChC,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC1B,gBAAgB,CACd,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,uBAAuB,GAChC,OAAO,CAAC,OAAO,CAAC,CAAC;IACpB,eAAe,CACb,MAAM,CAAC,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,uBAAuB,GAChC,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IACrB,cAAc,IAAI,OAAO,CAAC;CAC3B;AAED,KAAK,4BAA4B,GAAG,IAAI,CACtC,0BAA0B,EAC1B,UAAU,CACX,GAAG;IACF,QAAQ,CAAC,YAAY,EAAE,YAAY,CAAC;CACrC,CAAC;AAoNF,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,0BAA0B,GAClC,aAAa,CAMf;AAED,yDAAyD;AACzD,wBAAgB,mCAAmC,CACjD,OAAO,EAAE,4BAA4B,GACpC,aAAa,CAMf"}

package/dist/client.js

@@ -0,0 +1,129 @@
+import { createPolicyRunner, rejectedEventType, } from "./vault/policy.js";
+import { isValidKey, isValidKeyPrefix } from "./vault/vault-utils.js";
+import { InvalidCredentialKeyError } from "./vault/session-vault-errors.js";
+const SESSION_TTL_MS = 4 * 60 * 60 * 1000;
+const PROVIDER_FAILURE_ERROR = "provider operation failed";
+function operationStart() {
+    return {
+        timestamp: new Date().toISOString(),
+        monotonicMs: performance.now(),
+    };
+}
+function operationWithContext(fields, context) {
+    const caller = context?.caller;
+    return Object.freeze({
+        ...fields,
+        ...(caller
+            ? {
+                caller: Object.freeze({
+                    id: caller.id,
+                    ...(caller.kind !== undefined ? { kind: caller.kind } : {}),
+                }),
+            }
+            : {}),
+    });
+}
+class SecretsClientImpl {
+    provider;
+    policies;
+    providerName;
+    lastAccessAt = null;
+    constructor(provider, policies, providerName) {
+        this.provider = provider;
+        this.policies = policies;
+        const candidate = providerName ?? provider.name;
+        this.providerName = candidate?.trim() || "unknown";
+    }
+    isSessionValid() {
+        return (this.lastAccessAt !== null &&
+            Date.now() - this.lastAccessAt < SESSION_TTL_MS);
+    }
+    async storeCredential(key, value, context) {
+        const operation = operationWithContext({ type: "write", key }, context);
+        this.assertValidOperation(operation);
+        return this.execute(operation, "credential_write_failed", () => this.provider.store(key, value), (success) => success ? "credential_written" : "credential_write_failed", (success) => {
+            if (success)
+                this.lastAccessAt = Date.now();
+        });
+    }
+    async getCredential(key, context) {
+        const operation = operationWithContext({ type: "read", key }, context);
+        this.assertValidOperation(operation);
+        return this.execute(operation, "credential_read_failed", () => this.provider.retrieve(key), (value) => value === null ? "credential_read_missing" : "credential_read", (value) => {
+            if (value !== null)
+                this.lastAccessAt = Date.now();
+        });
+    }
+    async deleteCredential(key, context) {
+        const operation = operationWithContext({ type: "delete", key }, context);
+        this.assertValidOperation(operation);
+        return this.execute(operation, "credential_delete_failed", () => this.provider.delete(key), (success) => success ? "credential_deleted" : "credential_delete_failed");
+    }
+    async listCredentials(prefix, context) {
+        const operation = operationWithContext({ type: "enumerate", ...(prefix !== undefined ? { prefix } : {}) }, context);
+        this.assertValidOperation(operation);
+        return this.execute(operation, "credential_enumerate_failed", () => this.provider.listKeys(prefix), () => "credential_enumerated", (keys) => {
+            if (keys.length > 0)
+                this.lastAccessAt = Date.now();
+        }, (keys) => ({ keyCount: keys.length }));
+    }
+    assertValidOperation(operation) {
+        let error;
+        if (operation.type === "enumerate") {
+            if (operation.prefix !== undefined &&
+                !isValidKeyPrefix(operation.prefix)) {
+                error = new InvalidCredentialKeyError(operation.prefix, "enumerate", "prefix");
+            }
+        }
+        else if (operation.key !== undefined && !isValidKey(operation.key)) {
+            error = new InvalidCredentialKeyError(operation.key, operation.type, "key");
+        }
+        if (!error)
+            return;
+        const start = operationStart();
+        this.policies.runAfter(this.makeEvent(operation, rejectedEventType(operation), start, { error: error.message }));
+        throw error;
+    }
+    async execute(operation, failedType, invoke, successType, onSuccess, extras) {
+        const start = operationStart();
+        let frame;
+        frame = await this.policies.runBefore(operation, (error) => this.makeEvent(operation, rejectedEventType(operation), start, { error }));
+        let value;
+        try {
+            value = await invoke();
+        }
+        catch (error) {
+            this.policies.runAfter(this.makeEvent(operation, failedType, start, {
+                // Providers receive credential values on writes and may include one
+                // in a thrown message. Preserve the original error for the caller,
+                // but never forward provider-controlled text into an audit event.
+                error: PROVIDER_FAILURE_ERROR,
+            }), frame);
+            throw error;
+        }
+        onSuccess?.(value);
+        this.policies.runAfter(this.makeEvent(operation, successType(value), start, extras?.(value)), frame);
+        return value;
+    }
+    makeEvent(operation, type, start, extras = {}) {
+        return {
+            type,
+            // OCSF `time` is the operation start, not completion time.
+            timestamp: start.timestamp,
+            backend: this.providerName,
+            operation,
+            ...(operation.key !== undefined ? { key: operation.key } : {}),
+            ...(operation.prefix !== undefined ? { prefix: operation.prefix } : {}),
+            ...extras,
+            durationMs: performance.now() - start.monotonicMs,
+        };
+    }
+}
+export function createSecretsClient(options) {
+    return new SecretsClientImpl(options.provider, createPolicyRunner(options.policies ?? []), options.providerName);
+}
+/** @internal Legacy default-client construction seam. */
+export function createSecretsClientWithPolicyRunner(options) {
+    return new SecretsClientImpl(options.provider, options.policyRunner, options.providerName);
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

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

package/dist/compatibility.d.ts

@@ -0,0 +1,199 @@
+/**
+ * The compatibility floor: what an OLD `@centient/secrets` silently does wrong,
+ * published as data so a consumer can grade itself (#214).
+ *
+ * ## Why this exists
+ *
+ * Five consumers pin this package at four disjoint minors (`^0.5.0` … `0.10.0`)
+ * with no negotiation surface between them and the provider. Several releases
+ * closed defects whose only symptom, at the old version, is **silence**: a
+ * denied credential operation that leaves no audit trace, a keychain write that
+ * reports success into a keychain this context's reader cannot see, a malformed
+ * key that stores on one backend and reads as absent on the next. A consumer
+ * running such a version has no way to learn that from the package — the
+ * behaviour looks fine and the logs look clean.
+ *
+ * So the provider publishes the list. {@link COMPATIBILITY_FLOOR} names each
+ * closed gap, the version that closed it, and the symptom it presented before
+ * then; {@link assessCompatibility} turns an installed version into a grade a
+ * `doctor` command can print.
+ *
+ * ## What this is NOT
+ *
+ * **Never a boot-time refusal.** Nothing here runs at import, nothing throws
+ * from a constructor, and no vault path consults it. A package that refuses to
+ * load because the caller is old converts a documentation problem into an
+ * outage. Every function in this module is pure, total, and advisory: malformed
+ * input comes back as a typed `"unknown"` grade carrying the reason (P2, No
+ * Silent Degradation; P10, Honest Uncertainty), never as a throw.
+ *
+ * ## What a consumer does with it
+ *
+ * ```ts
+ * import { assessCompatibility, SECRETS_PACKAGE_VERSION } from "@centient/secrets";
+ *
+ * const assessment = assessCompatibility(SECRETS_PACKAGE_VERSION);
+ * if (assessment.grade !== "ok") {
+ *   for (const gap of assessment.openGaps) {
+ *     report(`${gap.severity}: ${gap.symptom} (fixed in ${gap.closedIn}, ${gap.reference})`);
+ *   }
+ * }
+ * ```
+ *
+ * `SECRETS_PACKAGE_VERSION` is the version of the build the consumer actually
+ * imported, so the assessment describes the code in that tree — not whatever is
+ * latest on the registry. A consumer auditing a *manifest* range instead (`the
+ * pin says ^0.6.0 — what does that admit at worst?`) uses {@link assessPin}.
+ *
+ * Issue: centient-labs/centient-sdk#214 (findings C6-27, C6-29, C6-61).
+ */
+/**
+ * The version of THIS build of `@centient/secrets`.
+ *
+ * Kept in step with `package.json` two ways: `scripts/sync-claudemd-versions.mjs`
+ * rewrites it during `pnpm run version-packages` (the same step that syncs the
+ * CLAUDE.md package table), and `tests/compatibility.test.ts` fails the build if
+ * the two ever disagree. A stale constant here would misgrade every consumer, so
+ * drift is a test failure rather than a silent wrong answer.
+ */
+export declare const SECRETS_PACKAGE_VERSION = "0.11.0";
+/**
+ * The oldest version {@link COMPATIBILITY_FLOOR} can honestly describe.
+ *
+ * `0.5.0` is the oldest release any current consumer pins, and the oldest one
+ * whose behaviour the table's entries were written against. Below it the table
+ * is not wrong so much as **incomplete** — returning its short list for a 0.4.x
+ * install would understate what is open — so {@link assessCompatibility} grades
+ * such a version `"unsupported"` and says so, rather than quietly reporting the
+ * gaps it happens to know about.
+ *
+ * This is an epistemic limit on the table, not a support policy and not a gate:
+ * an `"unsupported"` grade still returns every gap the table does know about.
+ */
+export declare const MIN_ASSESSABLE_VERSION = "0.5.0";
+/** How badly the gap bites a consumer still running below `closedIn`. */
+export type GapSeverity = "high" | "medium" | "low";
+/**
+ * One known behavioural gap, keyed by the version that closed it.
+ *
+ * A gap is **open** for an installed version `v` exactly when
+ * `v < closedIn` — there is no upper bound, because a fix that shipped is not
+ * un-shipped. Everything here is value-free public metadata: no credential
+ * material, no host paths, nothing that changes at runtime.
+ */
+export interface CompatibilityGap {
+    /** Stable machine-readable id. Never renamed — consumers may suppress by id. */
+    readonly id: string;
+    /** The first release in which the gap is closed. A valid `major.minor.patch`. */
+    readonly closedIn: string;
+    /** How badly this bites a consumer still below `closedIn`. */
+    readonly severity: GapSeverity;
+    /** One line, consumer-facing: what the OLD version does wrong. */
+    readonly symptom: string;
+    /** Issue or PR that closed it, `owner/repo#n`. */
+    readonly reference: string;
+    /**
+     * What the consumer must change when it adopts the fix, when adopting is not
+     * a pure no-op. Absent means "bump and nothing else". This is the field that
+     * turns the table from a scorecard into a bump plan.
+     */
+    readonly adoptionNote?: string;
+    /** The C6 audit finding this gap corresponds to, where one exists. */
+    readonly finding?: string;
+}
+/**
+ * The published floor — deeply frozen at module initialization (every field on
+ * a {@link CompatibilityGap} is a primitive, so freezing each entry plus the
+ * array is a complete freeze). `assessCompatibility()` defaults to this same
+ * object, so a runtime mutation — a JS consumer, a test helper, a cast past
+ * the `readonly` type — would silently change every later assessment in the
+ * process. Frozen, the mutation throws at the mutation site instead
+ * (mb:f/7e54ba; the same no-silent-degradation stance as the rest of this
+ * module).
+ */
+export declare const COMPATIBILITY_FLOOR: readonly CompatibilityGap[];
+/** The grade a consumer's installed version earns against the floor. */
+export type CompatibilityGrade = 
+/** At or above every known fix. Nothing in the table is open. */
+"ok"
+/** Assessable, but one or more known gaps are open. `openGaps` lists them. */
+ | "degraded"
+/** Below {@link MIN_ASSESSABLE_VERSION}: the table cannot claim to be complete. */
+ | "unsupported"
+/** The version could not be parsed. `reason` says why. Never a throw. */
+ | "unknown";
+/**
+ * The result of grading one version against the floor. Every field is derived
+ * and value-free; the input is echoed back so a caller can see what was graded
+ * (P6, Single Source of Truth — echo interpreted parameters).
+ */
+export interface CompatibilityAssessment {
+    readonly grade: CompatibilityGrade;
+    /** The version as given, echoed verbatim — including unparseable input. */
+    readonly installedVersion: string;
+    /** The version of the build that produced this assessment. */
+    readonly currentVersion: string;
+    /** The floor below which the table is incomplete. */
+    readonly minAssessableVersion: string;
+    /**
+     * Gaps open at `installedVersion`, oldest fix first. Empty for `"ok"` and for
+     * `"unknown"` — and for `"unknown"` that emptiness means `not assessed`, which
+     * is why the grade, not the list length, is what a caller branches on.
+     */
+    readonly openGaps: readonly CompatibilityGap[];
+    /** The worst severity among `openGaps`, or `null` when there are none. */
+    readonly highestSeverity: GapSeverity | null;
+    /** One line suitable for a doctor's status column. */
+    readonly summary: string;
+    /** Why the grade is `"unknown"` or `"unsupported"`. Absent otherwise. */
+    readonly reason?: string;
+}
+/**
+ * Grade an installed version against the compatibility floor.
+ *
+ * Pure and total: it reads no environment, touches no keychain, and **never
+ * throws** — a version string it cannot parse comes back as
+ * `grade: "unknown"` naming the problem. Totality is enforced here rather than
+ * assumed of the parser: input is narrowed by this module's own guard, so a JS
+ * caller handing it `null`, `undefined`, a number or an object gets the same
+ * typed `"unknown"` result as a misspelt version, never an exception. Call it
+ * from a `doctor`, a startup log line, or a CI check; do not call it from a
+ * code path that would refuse to run on the answer.
+ *
+ * @param installedVersion - the version actually installed in the consumer's
+ *   tree. Import {@link SECRETS_PACKAGE_VERSION} for that; a leading `v` and
+ *   surrounding whitespace are tolerated.
+ * @param floor - the gap table to grade against. Defaults to
+ *   {@link COMPATIBILITY_FLOOR}; injectable so a test can grade a fixture table
+ *   without pinning itself to the shipped one.
+ */
+export declare function assessCompatibility(installedVersion: string, floor?: readonly CompatibilityGap[]): CompatibilityAssessment;
+/**
+ * The lowest version a dependency range admits, or `null` when the range form
+ * is one this helper does not understand.
+ *
+ * Deliberately narrow: it recognises the forms that actually appear in the
+ * consumers' manifests — `^x.y.z`, `~x.y.z`, `>=x.y.z` and a bare `x.y.z` — and
+ * returns `null` for everything else rather than guessing. A guess here would
+ * grade the wrong version and report a clean bill of health for a pin nobody
+ * checked.
+ *
+ * The accepted grammar is matched whole and enumerated on
+ * {@link SUPPORTED_RANGE}; nothing outside it is partially interpreted. Total:
+ * a non-string, an empty string, and every unsupported form all return `null`.
+ */
+export declare function lowestVersionInRange(range: string): string | null;
+/**
+ * Grade a manifest **pin** by its worst admissible version.
+ *
+ * `assessCompatibility` answers "what is open in the build I imported"; this
+ * answers "what could be open in any build this pin admits". A `^0.6.0` pin can
+ * resolve to any 0.6.x, so the version worth grading is its base — which is also
+ * the one a lockfile that has never been refreshed is most likely holding.
+ *
+ * Returns `grade: "unknown"` carrying the reason for a range form
+ * {@link lowestVersionInRange} does not recognise — including a non-string a JS
+ * caller slipped past the signature. Never throws.
+ */
+export declare function assessPin(pin: string, floor?: readonly CompatibilityGap[]): CompatibilityAssessment;
+//# sourceMappingURL=compatibility.d.ts.map

package/dist/compatibility.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compatibility.d.ts","sourceRoot":"","sources":["../src/compatibility.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AAIH;;;;;;;;GAQG;AACH,eAAO,MAAM,uBAAuB,WAAW,CAAC;AAEhD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,sBAAsB,UAAU,CAAC;AAE9C,yEAAyE;AACzE,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAC;AAQpD;;;;;;;GAOG;AACH,MAAM,WAAW,gBAAgB;IAC/B,gFAAgF;IAChF,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,iFAAiF;IACjF,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,8DAA8D;IAC9D,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC;IAC/B,kEAAkE;IAClE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,kDAAkD;IAClD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;;;;OAIG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,sEAAsE;IACtE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AA+ED;;;;;;;;;GASG;AACH,eAAO,MAAM,mBAAmB,EAAE,SAAS,gBAAgB,EAE1D,CAAC;AA4DF,wEAAwE;AACxE,MAAM,MAAM,kBAAkB;AAC5B,iEAAiE;AAC/D,IAAI;AACN,8EAA8E;GAC5E,UAAU;AACZ,mFAAmF;GACjF,aAAa;AACf,yEAAyE;GACvE,SAAS,CAAC;AAEd;;;;GAIG;AACH,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,KAAK,EAAE,kBAAkB,CAAC;IACnC,2EAA2E;IAC3E,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,8DAA8D;IAC9D,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,qDAAqD;IACrD,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAC;IACtC;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAC/C,0EAA0E;IAC1E,QAAQ,CAAC,eAAe,EAAE,WAAW,GAAG,IAAI,CAAC;IAC7C,sDAAsD;IACtD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,yEAAyE;IACzE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,mBAAmB,CACjC,gBAAgB,EAAE,MAAM,EACxB,KAAK,GAAE,SAAS,gBAAgB,EAAwB,GACvD,uBAAuB,CAwEzB;AA0FD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAGjE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,CACvB,GAAG,EAAE,MAAM,EACX,KAAK,GAAE,SAAS,gBAAgB,EAAwB,GACvD,uBAAuB,CAezB"}