@nomix-ai/nomix-harness 0.2.5 → 0.2.6

package/dist/kernel/credentials/lib/types/index.d.ts

@@ -8,14 +8,65 @@
  * @module @nomix-ai/nomix-credentials
  */
 import { Context, Service } from '../../../cordis/lib/index.js';
-import type { CredentialRef } from './types.ts';
-export type { CredentialRef } from './types.ts';
+import type { CredentialKey, CredentialRecord, CredentialRef } from './types.ts';
+export type { ApiKeyRecord, CredentialKey, CredentialRecord, CredentialRef, GrantRecord } from './types.ts';
 /**
  * Brand a raw string as a {@link CredentialRef}.
  * @param value - candidate reference; a POSIX shell identifier such as `DEEPSEEK_API_KEY`.
  * @returns the branded reference.
  */
 export declare function credentialRef(value: string): CredentialRef;
+/**
+ * Whether a raw string could name a reference at all. Consumers that receive
+ * environment-variable names from somewhere else — a provider library's own
+ * ambient discovery, a hook payload — ask this before resolving, because a name
+ * outside the grammar has no reference to miss and should read as "not set"
+ * rather than as a thrown error.
+ * @param value - candidate reference.
+ * @returns true when {@link credentialRef} would accept it.
+ */
+export declare function isCredentialRefName(value: string): boolean;
+/**
+ * Whether a raw string could be a {@link credentialKey} segment at all.
+ * Consumers whose addressing units come from somewhere else — a settings dict
+ * key, a library's own provider id — ask this before building a key, because a
+ * unit outside the grammar can never have stored a record and should read as
+ * "nothing stored" rather than as a thrown error.
+ * @param value - candidate segment.
+ * @returns true when {@link credentialKey} would accept it as either segment.
+ */
+export declare function isCredentialKeySegment(value: string): boolean;
+/**
+ * Brand a scope and an id as a {@link CredentialKey}.
+ * @param scope - the owning plugin's registered name, such as `llm-pi-ai`.
+ * @param id - that plugin's own addressing unit, such as a provider route key.
+ * @returns the branded key.
+ * @throws TypeError when either segment is not a lowercase hyphenated identifier.
+ */
+export declare function credentialKey(scope: string, id: string): CredentialKey;
+/**
+ * Brand a stored `<scope>/<id>` string as a {@link CredentialKey}. This is the
+ * read half of {@link credentialKey}, for a provider admitting keys off disk.
+ * @param value - candidate key in its joined form.
+ * @returns the branded key.
+ * @throws TypeError when the value is not exactly two valid segments.
+ */
+export declare function parseCredentialKey(value: string): CredentialKey;
+/**
+ * The owning plugin's name for one key. A record whose scope names no
+ * currently registered owner is an orphan, which a configuration surface must
+ * report as such rather than as a working credential.
+ * @param key - the key to read.
+ * @returns the scope segment.
+ */
+export declare function credentialKeyScope(key: CredentialKey): string;
+/**
+ * The owning plugin's own addressing unit for one key — the half that plugin
+ * chose, such as a provider route.
+ * @param key - the key to read.
+ * @returns the id segment.
+ */
+export declare function credentialKeyId(key: CredentialKey): string;
 /** One resolved credential value and the source layer that supplied it. */
 export interface ResolvedCredential {
     /** The non-empty secret value. */
@@ -32,16 +83,47 @@ export interface CredentialInfo {
     /** Whether {@link CredentialProvider.set} would currently succeed for this reference. */
     writable: boolean;
 }
+/** Presence and writability facts for one record, safe for configuration UIs — never the value. */
+export interface CredentialRecordInfo {
+    /**
+     * Whether a record is stored. Unlike a reference, presence alone answers
+     * this: an {@link ApiKeyRecord} carrying neither a key nor environment
+     * values states that its owner confirmed ambient authentication, which is
+     * configured, not blank.
+     */
+    configured: boolean;
+    /** Discriminant of the stored record; absent while none is stored. */
+    kind?: CredentialRecord['kind'];
+    /** Whether {@link CredentialProvider.modifyRecord} would currently succeed. */
+    writable: boolean;
+}
+/** One stored record's address and tag, for enumeration — never its value. */
+export interface CredentialRecordEntry {
+    /** The record's address. */
+    key: CredentialKey;
+    /** Discriminant of the stored record. */
+    kind: CredentialRecord['kind'];
+}
 declare module '@nomix-ai/cordis' {
     interface Context {
         credentials: CredentialProvider;
     }
 }
 /**
- * Abstract credential service. Providers implement the four operations over
- * their source layers; one seam-wide rule binds them all: an empty stored
- * value is absent everywhere — `resolve` skips it, `describe` reports it
- * unconfigured — so a blank never masquerades as a configured secret.
+ * Abstract credential service over two key spaces that answer two questions.
+ *
+ * A {@link CredentialRef} answers "what is behind this environment-variable
+ * name", layered over the process environment, the provider-managed store, and
+ * `.env` files. One seam-wide rule binds that half: an empty stored value is
+ * absent everywhere — `resolve` skips it, `describe` reports it unconfigured —
+ * so a blank never masquerades as a configured secret.
+ *
+ * A {@link CredentialKey} answers "what credential does this plugin hold for
+ * this id". Nothing can layer here — an authorization grant has no
+ * environment to be read from — so presence of the record is the whole fact,
+ * and {@link modifyRecord} is the only write path because a correct write
+ * depends on the current value (a token refresh is read-decide-replace under
+ * one lock).
  */
 export declare abstract class CredentialProvider extends Service {
     constructor(ctx: Context);
@@ -78,7 +160,46 @@ export declare abstract class CredentialProvider extends Service {
      */
     abstract unset(ref: CredentialRef): Promise<void>;
     /**
-     * Fan `credentials/updated` out with contained listener failures: every
+     * Read one stored record. The value is returned as its owner wrote it; a
+     * {@link GrantRecord} payload is not interpreted on the way out.
+     * @param key - the record to read.
+     * @returns the record, or `undefined` while none is stored.
+     */
+    abstract readRecord(key: CredentialKey): Promise<CredentialRecord | undefined>;
+    /**
+     * Describe one record for configuration surfaces without exposing its value.
+     * @param key - the record to describe.
+     * @returns presence, discriminant, and writability.
+     */
+    abstract describeRecord(key: CredentialKey): Promise<CredentialRecordInfo>;
+    /**
+     * Enumerate every stored record's address and tag. Unlike the reference
+     * half, which has no enumeration because configuration surfaces learn which
+     * references exist from settings schemas, records have no such discovery
+     * path: a surface that cannot list them cannot show what a user is
+     * authorized for, nor find an orphan left by an uninstalled plugin.
+     * @returns every stored record, values excluded.
+     */
+    abstract listRecords(): Promise<readonly CredentialRecordEntry[]>;
+    /**
+     * Serialized read-modify-write over one record — the only write path.
+     * `mutate` sees the record as it stands at the moment the write is
+     * exclusive, and returning `undefined` leaves the entry untouched. Exclusion
+     * holds across processes where the backing store supports it, which is what
+     * makes a token refresh safe: two processes rotating one refresh token
+     * concurrently would otherwise lose whichever wrote first.
+     * @param key - the record to modify.
+     * @param mutate - receives the current record and returns its replacement, or `undefined` to leave it.
+     * @returns the record after the write, or the current one when `mutate` declined.
+     */
+    abstract modifyRecord(key: CredentialKey, mutate: (current: CredentialRecord | undefined) => Promise<CredentialRecord | undefined>): Promise<CredentialRecord | undefined>;
+    /**
+     * Remove one record; removing an absent record is a no-op.
+     * @param key - the record to remove.
+     */
+    abstract deleteRecord(key: CredentialKey): Promise<void>;
+    /**
+     * Fan `credentials/reference-updated` out with contained listener failures: every
      * listener runs, and a sync throw or async rejection is logged without
      * changing the committed operation's outcome — except `INVARIANT`-coded
      * failures, which rethrow after every listener ran (the rethrow reaches the
@@ -89,6 +210,14 @@ export declare abstract class CredentialProvider extends Service {
      * @param ref - the reference whose stored value changed.
      */
     protected notifyUpdated(ref: CredentialRef): void;
+    /**
+     * Fan `credentials/record-updated` out on exactly the terms
+     * {@link notifyUpdated} documents, for the record half of the seam.
+     * @param key - the record whose stored value changed.
+     */
+    protected notifyRecordUpdated(key: CredentialKey): void;
+    /** The contained dispatch both notifications run through; see {@link notifyUpdated}. */
+    private fanOut;
     /** Contained-listener diagnostic shared by the sync and async failure paths. */
     private warnListenerFailure;
 }

package/dist/kernel/credentials/lib/types/index.js

@@ -9,32 +9,116 @@
  */
 import { Service } from '../../../cordis/lib/index.js';
 const REF_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/** Both halves of a {@link CredentialKey}; the `/` between them is what keeps it out of {@link REF_PATTERN}. */
+const KEY_SEGMENT_PATTERN = /^[a-z][a-z0-9-]*$/;
 /**
  * Brand a raw string as a {@link CredentialRef}.
  * @param value - candidate reference; a POSIX shell identifier such as `DEEPSEEK_API_KEY`.
  * @returns the branded reference.
  */
 export function credentialRef(value) {
-    if (!REF_PATTERN.test(value)) {
+    if (!isCredentialRefName(value)) {
         throw new TypeError(`credential ref "${value}" must match ${String(REF_PATTERN)}`);
     }
     return value;
 }
 /**
- * Abstract credential service. Providers implement the four operations over
- * their source layers; one seam-wide rule binds them all: an empty stored
- * value is absent everywhere — `resolve` skips it, `describe` reports it
- * unconfigured — so a blank never masquerades as a configured secret.
+ * Whether a raw string could name a reference at all. Consumers that receive
+ * environment-variable names from somewhere else — a provider library's own
+ * ambient discovery, a hook payload — ask this before resolving, because a name
+ * outside the grammar has no reference to miss and should read as "not set"
+ * rather than as a thrown error.
+ * @param value - candidate reference.
+ * @returns true when {@link credentialRef} would accept it.
+ */
+export function isCredentialRefName(value) {
+    return REF_PATTERN.test(value);
+}
+/**
+ * Whether a raw string could be a {@link credentialKey} segment at all.
+ * Consumers whose addressing units come from somewhere else — a settings dict
+ * key, a library's own provider id — ask this before building a key, because a
+ * unit outside the grammar can never have stored a record and should read as
+ * "nothing stored" rather than as a thrown error.
+ * @param value - candidate segment.
+ * @returns true when {@link credentialKey} would accept it as either segment.
+ */
+export function isCredentialKeySegment(value) {
+    return KEY_SEGMENT_PATTERN.test(value);
+}
+/**
+ * Brand a scope and an id as a {@link CredentialKey}.
+ * @param scope - the owning plugin's registered name, such as `llm-pi-ai`.
+ * @param id - that plugin's own addressing unit, such as a provider route key.
+ * @returns the branded key.
+ * @throws TypeError when either segment is not a lowercase hyphenated identifier.
+ */
+export function credentialKey(scope, id) {
+    for (const segment of [scope, id]) {
+        if (!KEY_SEGMENT_PATTERN.test(segment)) {
+            throw new TypeError(`credential key segment "${segment}" must match ${String(KEY_SEGMENT_PATTERN)}`);
+        }
+    }
+    return `${scope}/${id}`;
+}
+/**
+ * Brand a stored `<scope>/<id>` string as a {@link CredentialKey}. This is the
+ * read half of {@link credentialKey}, for a provider admitting keys off disk.
+ * @param value - candidate key in its joined form.
+ * @returns the branded key.
+ * @throws TypeError when the value is not exactly two valid segments.
+ */
+export function parseCredentialKey(value) {
+    const segments = value.split('/');
+    const [scope, id] = segments;
+    if (segments.length !== 2 || scope === undefined || id === undefined) {
+        throw new TypeError(`credential key "${value}" must be "<scope>/<id>"`);
+    }
+    return credentialKey(scope, id);
+}
+/**
+ * The owning plugin's name for one key. A record whose scope names no
+ * currently registered owner is an orphan, which a configuration surface must
+ * report as such rather than as a working credential.
+ * @param key - the key to read.
+ * @returns the scope segment.
+ */
+export function credentialKeyScope(key) {
+    // The brand's only constructors both validate two segments, so the split
+    // cannot come back short here.
+    return key.slice(0, key.indexOf('/'));
+}
+/**
+ * The owning plugin's own addressing unit for one key — the half that plugin
+ * chose, such as a provider route.
+ * @param key - the key to read.
+ * @returns the id segment.
+ */
+export function credentialKeyId(key) {
+    return key.slice(key.indexOf('/') + 1);
+}
+/**
+ * Abstract credential service over two key spaces that answer two questions.
+ *
+ * A {@link CredentialRef} answers "what is behind this environment-variable
+ * name", layered over the process environment, the provider-managed store, and
+ * `.env` files. One seam-wide rule binds that half: an empty stored value is
+ * absent everywhere — `resolve` skips it, `describe` reports it unconfigured —
+ * so a blank never masquerades as a configured secret.
+ *
+ * A {@link CredentialKey} answers "what credential does this plugin hold for
+ * this id". Nothing can layer here — an authorization grant has no
+ * environment to be read from — so presence of the record is the whole fact,
+ * and {@link modifyRecord} is the only write path because a correct write
+ * depends on the current value (a token refresh is read-decide-replace under
+ * one lock).
  */
 export class CredentialProvider extends Service {
     constructor(ctx) {
         super(ctx, 'credentials');
     }
-    /* jscpd:ignore-start -- deliberate symmetry with the settings seam's commit
-       fan-out: the contained-dispatch shape is the reviewed listener-lifecycle
-       contract, and extracting it would couple the two seams' event semantics. */
     /**
-     * Fan `credentials/updated` out with contained listener failures: every
+     * Fan `credentials/reference-updated` out with contained listener failures: every
      * listener runs, and a sync throw or async rejection is logged without
      * changing the committed operation's outcome — except `INVARIANT`-coded
      * failures, which rethrow after every listener ran (the rethrow reaches the
@@ -45,14 +129,29 @@ export class CredentialProvider extends Service {
      * @param ref - the reference whose stored value changed.
      */
     notifyUpdated(ref) {
+        this.fanOut('credentials/reference-updated', ref);
+    }
+    /**
+     * Fan `credentials/record-updated` out on exactly the terms
+     * {@link notifyUpdated} documents, for the record half of the seam.
+     * @param key - the record whose stored value changed.
+     */
+    notifyRecordUpdated(key) {
+        this.fanOut('credentials/record-updated', key);
+    }
+    /* jscpd:ignore-start -- deliberate symmetry with the settings seam's commit
+       fan-out: the contained-dispatch shape is the reviewed listener-lifecycle
+       contract, and extracting it would couple the two seams' event semantics. */
+    /** The contained dispatch both notifications run through; see {@link notifyUpdated}. */
+    fanOut(event, subject) {
         let invariantFailure;
-        const args = ['credentials/updated', ref];
+        const args = [event, subject];
         for (const listener of this.ctx.events.dispatch('emit', args)) {
             try {
-                const returned = listener(ref);
+                const returned = listener(subject);
                 if (returned != null && typeof returned.then === 'function') {
                     void Promise.resolve(returned).then(undefined, (error) => {
-                        this.warnListenerFailure(ref, error);
+                        this.warnListenerFailure(event, subject, error);
                     });
                 }
             }
@@ -61,7 +160,7 @@ export class CredentialProvider extends Service {
                     invariantFailure ??= error;
                     continue;
                 }
-                this.warnListenerFailure(ref, error);
+                this.warnListenerFailure(event, subject, error);
             }
         }
         if (invariantFailure !== undefined)
@@ -69,8 +168,8 @@ export class CredentialProvider extends Service {
     }
     /* jscpd:ignore-end */
     /** Contained-listener diagnostic shared by the sync and async failure paths. */
-    warnListenerFailure(ref, error) {
-        this.ctx.logger.warn('credentials: a credentials/updated listener for "%s" failed', ref);
+    warnListenerFailure(event, subject, error) {
+        this.ctx.logger.warn('credentials: a %s listener for "%s" failed', event, subject);
         this.ctx.logger.warn(error);
     }
 }

package/dist/kernel/credentials/lib/types/invariant.js

@@ -8,7 +8,7 @@ export const name = 'credentials-invariant';
 /** Service required before the companion can reserve package ownership. */
 export const inject = ['invariants'];
 /**
- * Install the commit-event lifecycle contract: `credentials/updated` names a
+ * Install the commit-event lifecycle contract: `credentials/reference-updated` names a
  * committed provider-source change, so it can only fire while a credentials
  * service is live — an emission after disposal means a provider leaked work
  * past its teardown quiescence. The value relation itself (`describe`
@@ -16,9 +16,9 @@ export const inject = ['invariants'];
  * each provider's own suite.
  */
 const install = (ctx, fail) => {
-    ctx.on('credentials/updated', (ref) => {
+    ctx.on('credentials/reference-updated', (ref) => {
         if (ctx.get('credentials') === undefined) {
-            fail(`credentials/updated for "${ref}" emitted without a live credentials service`);
+            fail(`credentials/reference-updated for "${ref}" emitted without a live credentials service`);
         }
     });
 };

package/dist/kernel/credentials/lib/types/types.d.ts

@@ -1,14 +1,56 @@
 /**
- * Client-safe type surface of the credential-reference seam: the reference
- * brand and the seam's Cordis event declaration. Types only — no runtime code,
- * and nothing here reaches a Host-only symbol, so a Client compilation face
- * reads exactly the signature the Host emits.
+ * Client-safe type surface of the credential seam: the two key brands, the
+ * stored-record union, and the seam's Cordis event declarations. Types only —
+ * no runtime code, and nothing here reaches a Host-only symbol, so a Client
+ * compilation face reads exactly the signature the Host emits.
  *
  * @module @nomix-ai/nomix-credentials/types
  */
 import type { Branded } from '../../../brand/lib/index.js';
 /** Nominal reference to one credential: a POSIX-style environment-variable name. */
 export type CredentialRef = Branded<'CredentialRef'>;
+/**
+ * Nominal address of one stored credential record: `<scope>/<id>`, where
+ * `scope` is the registered name of the plugin that owns the record and `id`
+ * is that plugin's own addressing unit (an LLM adapter uses its provider route
+ * key).
+ *
+ * The scope is the owner rather than the domain because a record's payload is
+ * written in its owner's format: two plugins serving the same provider name
+ * would otherwise read each other's payload, and a record left behind by an
+ * uninstalled plugin could not be told apart from a live one. The `/` also
+ * keeps this grammar disjoint from {@link CredentialRef}, so the two key
+ * spaces can never collide.
+ */
+export type CredentialKey = Branded<'CredentialKey'>;
+/**
+ * A credential the harness itself understands: an api key, provider
+ * environment values, or both. Either field may be absent — a record carrying
+ * neither states that the owner confirmed this route authenticates from its
+ * own ambient discovery, which is a different fact from having no record.
+ */
+export interface ApiKeyRecord {
+    /** Discriminant. */
+    readonly kind: 'api-key';
+    /** The non-empty secret value, when this credential is a key at all. */
+    readonly key?: string;
+    /** Provider environment values such as `AWS_PROFILE`; names are POSIX identifiers. */
+    readonly env?: Readonly<Record<string, string>>;
+}
+/**
+ * The product of one authorization grant, kept verbatim for its owner. The
+ * seam never reads, validates, or reshapes {@link payload}: it is written in
+ * the owning plugin's format and only that plugin can interpret it. The single
+ * constraint is that it survives a JSON round trip.
+ */
+export interface GrantRecord {
+    /** Discriminant. */
+    readonly kind: 'grant';
+    /** Owner-defined JSON value; opaque to the seam and to every other plugin. */
+    readonly payload: unknown;
+}
+/** One durable credential record, tagged by what the seam may do with it. */
+export type CredentialRecord = ApiKeyRecord | GrantRecord;
 declare module '@nomix-ai/cordis' {
     interface Events {
         /**
@@ -23,7 +65,18 @@ declare module '@nomix-ai/cordis' {
          * @param ref - the reference whose stored value changed.
          * @mode emit
          */
-        'credentials/updated'(ref: CredentialRef): void;
+        'credentials/reference-updated'(ref: CredentialRef): void;
+        /**
+         * Committed change to a stored credential record: a `modifyRecord` that
+         * wrote, a `deleteRecord` that removed, or an external edit observed in
+         * storage. Separate from `credentials/reference-updated` because the two key
+         * grammars are disjoint — a listener that received both on one event could
+         * not tell which space a subject belongs to. Listener failures are
+         * contained on the same terms as `credentials/reference-updated`.
+         * @param key - the record whose stored value changed.
+         * @mode emit
+         */
+        'credentials/record-updated'(key: CredentialKey): void;
     }
 }
 //# sourceMappingURL=types.d.ts.map

package/dist/kernel/credentials/lib/types/types.js

@@ -1,8 +1,8 @@
 /**
- * Client-safe type surface of the credential-reference seam: the reference
- * brand and the seam's Cordis event declaration. Types only — no runtime code,
- * and nothing here reaches a Host-only symbol, so a Client compilation face
- * reads exactly the signature the Host emits.
+ * Client-safe type surface of the credential seam: the two key brands, the
+ * stored-record union, and the seam's Cordis event declarations. Types only —
+ * no runtime code, and nothing here reaches a Host-only symbol, so a Client
+ * compilation face reads exactly the signature the Host emits.
  *
  * @module @nomix-ai/nomix-credentials/types
  */

package/dist/kernel/credentials/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@nomix-ai/nomix-credentials",
   "description": "Abstract credential seam (ctx.credentials): settings carry references to secrets, providers own the values",
-  "version": "0.2.5",
+  "version": "0.2.6",
   "publishConfig": {
     "access": "public"
   },