@sema-agent/primitives 7.57.0 → 7.58.0

package/README.md

@@ -1,9 +1,10 @@
 # @sema-agent/primitives
 
 Low-level definitions of the sema engine that every layer may import: no policy of any layer, no state, no
-dependencies. Today it holds one member, the credential reference. It is compiled from the same source the engine
-embeds, so an acceptance gate, a settings validator or an admin form reads the same closed set through the same function
-as the engine does. Runs in Node and in browsers; ships its own types.
+dependencies. Today it holds one member, the credential reference. The engine depends on this package and reads it by
+name, so in a project that installs both there is one copy: an acceptance gate, a settings validator or an admin form
+reads the same closed set through the same function object as the engine does. Runs in Node and in browsers; ships its
+own types.
 
 ## Install
 
@@ -18,6 +19,10 @@ ES modules only (`"type": "module"`), Node >= 20.18.1 where Node is used. One en
 `@sema-agent/primitives@X.Y.Z` is cut with `@sema-agent/core@X.Y.Z`: the same version number, built from the same
 commit. A package version moves with every core release whether or not the primitives changed.
 
+`@sema-agent/core@X.Y.Z` depends on `@sema-agent/primitives@X.Y.Z` exactly. A project that also imports this package
+names the same version as its core (or a range npm can resolve to it); then `npm ls @sema-agent/primitives` shows one
+copy. Naming another version installs two — npm keeps core's own beside it — and the two answer for different versions.
+
 ## The credential reference
 
 A declaration names a credential by reference instead of carrying its value. The reference is one of a closed set of

package/dist/credential-ref.d.ts

@@ -1,5 +1,17 @@
+/**
+ * The credential reference: how a declaration names a credential without carrying one. This module says which references
+ * exist and whether a value is one, so the engine's door, an acceptance gate, a settings validator and an admin form read
+ * one closed set through one function. It resolves nothing, reads no environment and holds no state.
+ * Zero dependencies: no builtin, no import, so the same file runs in Node and in a browser.
+ */
+/** The closed set of kinds. A value whose `kind` is not in it is refused, never guessed at. */
 export declare const CREDENTIAL_REF_KINDS: readonly ["env", "vault", "handle", "assertion"];
 export type CredentialRefKind = (typeof CREDENTIAL_REF_KINDS)[number];
+/**
+ * A reference, by kind. `env` names variables of the resolver's environment (header name → variable name for an http
+ * peer, child variable → variable name for a stdio peer; the maps have no prototype); `vault` names a stored entry;
+ * `handle` is an opaque id the deployment minted; `assertion` names the audience a short-lived assertion is requested for.
+ */
 export type CredentialRef = {
     readonly kind: "env";
     readonly headers?: Readonly<Record<string, string>>;
@@ -14,15 +26,31 @@ export type CredentialRef = {
     readonly kind: "assertion";
     readonly audience: string;
 };
+/** What an acceptance gate may do with a reference that arrives on the request surface (the deployment may write any kind). */
 export type CredentialRefRequestAdmission = "refused" | "own_entry";
 type TrustRow = {
     readonly request: CredentialRefRequestAdmission;
 };
+/**
+ * Where each kind may come from. `refused`: a request surface may not carry it (an environment name would read any
+ * variable of the resolver's process, a handle names someone else's credential, an assertion is minted by the deployment);
+ * `own_entry`: only for an entry that belongs to the submitting principal. A row per kind and nothing else (no prototype);
+ * look a kind up only after `readCredentialRef` accepted the value. A shape for a gate to read; it authenticates nothing.
+ */
 export declare const CREDENTIAL_REF_TRUST: Readonly<Record<CredentialRefKind, TrustRow>>;
+/** The longest text member (entry, id, audience, header name, variable name) a reference may carry, in UTF-16 code units. */
 export declare const CREDENTIAL_REF_TEXT_MAX = 2048;
+/** The most entries one name map (`headers`, `env`) of an `env` reference may hold. */
 export declare const CREDENTIAL_REF_MAP_MAX = 64;
+/** Why a value is not a reference; each reason is its own exit. */
 export declare const CREDENTIAL_REF_PROBLEM_REASONS: readonly ["not_a_record", "unknown_kind", "missing_field", "extra_field", "bad_value"];
 export type CredentialRefProblemReason = (typeof CREDENTIAL_REF_PROBLEM_REASONS)[number];
+/**
+ * The first fault found, in this order: not an ordinary record; `kind` missing, not text or outside the set; a member the
+ * kind does not have; a member it needs (for `env`, one of `headers` and `env`, written `headers|env`); a member of the
+ * wrong form. A `kind` or `field` read off the caller's value is untrusted text, cut to 64 characters with unsafe
+ * characters replaced; fence it before rendering it where markup is interpreted.
+ */
 export type CredentialRefProblem = {
     readonly reason: "not_a_record";
 } | {
@@ -48,5 +76,14 @@ export type CredentialRefReading = {
     readonly ok: false;
     readonly problem: CredentialRefProblem;
 };
+/**
+ * The one reader of a credential reference: a fresh frozen copy that the caller's later writes cannot reach (forward the
+ * copy, never the value read), or the first problem. Nothing inside it throws: a value whose members cannot be read (a
+ * revoked or throwing Proxy) is `not_a_record`, or the `bad_value` of the map that holds it. A getter is refused and never
+ * called, no prototype is read for a member, and a Proxy's own traps (on the value, its maps or its prototype) are the
+ * caller's code and run as for any property read. Text is compared as written: nothing is normalised, and visually
+ * confusable text is not judged. With no stack left a valid value may be refused (any reason), never an invalid one
+ * accepted, and the call itself may throw a `RangeError` before it is entered.
+ */
 export declare function readCredentialRef(value: unknown): CredentialRefReading;
 export {};

package/dist/index.d.ts

@@ -1 +1,2 @@
+/** The package entry of `@sema-agent/primitives`; core imports the package by name, never these modules. */
 export { CREDENTIAL_REF_KINDS, CREDENTIAL_REF_TRUST, CREDENTIAL_REF_TEXT_MAX, CREDENTIAL_REF_MAP_MAX, CREDENTIAL_REF_PROBLEM_REASONS, readCredentialRef, type CredentialRef, type CredentialRefKind, type CredentialRefRequestAdmission, type CredentialRefProblem, type CredentialRefProblemReason, type CredentialRefReading, } from "./credential-ref.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/primitives",
-  "version": "7.57.0",
+  "version": "7.58.0",
   "private": false,
   "description": "Shared low-level definitions of the sema engine, importable by any layer: the credential reference (closed set of kinds, one reader). Zero dependencies.",
   "type": "module",
@@ -29,7 +29,7 @@
     "access": "public"
   },
   "scripts": {
-    "build": "tsc -p tsconfig.json"
+    "build": "tsc -p tsconfig.json && tsc -p tsconfig.json --emitDeclarationOnly --removeComments false"
   },
-  "gitHead": "84be0e09dcdd8e157f88f083241ceafedc0f33aa"
+  "gitHead": "05f1a14710d078da0b338fe8712e16f8d790f6bd"
 }