@sema-agent/primitives 0.0.0-stage → 7.58.0

package/LICENSE

@@ -0,0 +1,106 @@
+Business Source License 1.1
+
+Parameters
+
+Licensor:             clay (github.com/clayboby)
+Licensed Work:        @sema-agent/core (sema-core) and the satellite packages
+                      published from this repository (currently
+                      @sema-agent/mods-kernel, @sema-agent/primitives and @sema-agent/core-stores-sql)
+                      (formerly published as @sema-ai/core)
+                      The Licensed Work is (c) 2026 clay.
+Additional Use Grant: You may make production use of the Licensed Work for
+                      personal, educational, research, or other
+                      non-commercial purposes. Commercial production use
+                      requires a commercial license from the Licensor.
+Change Date:          2030-07-13
+Change License:       Apache License, Version 2.0
+
+For information about alternative licensing arrangements for the Licensed
+Work, please contact the Licensor.
+
+Notice
+
+The Business Source License (this document, or the "License") is not an Open
+Source license. However, the Licensed Work will eventually be made available
+under an Open Source License, as stated in this License.
+
+License text copyright (c) 2017 MariaDB Corporation Ab, All Rights Reserved.
+"Business Source License" is a trademark of MariaDB Corporation Ab.
+
+-----------------------------------------------------------------------------
+
+Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative
+works, redistribute, and make non-production use of the Licensed Work. The
+Licensor may make an Additional Use Grant, above, permitting limited
+production use.
+
+Effective on the Change Date, or the fourth anniversary of the first publicly
+available distribution of a specific version of the Licensed Work under this
+License, whichever comes first, the Licensor hereby grants you rights under
+the terms of the Change License, and the rights granted in the paragraph
+above terminate.
+
+If your use of the Licensed Work does not comply with the requirements
+currently in effect as described in this License, you must purchase a
+commercial license from the Licensor, its affiliated entities, or authorized
+resellers, or you must refrain from using the Licensed Work.
+
+All copies of the original and modified Licensed Work, and derivative works
+of the Licensed Work, are subject to this License. This License applies
+separately for each version of the Licensed Work and the Change Date may vary
+for each version of the Licensed Work released by Licensor.
+
+You must conspicuously display this License on each original or modified copy
+of the Licensed Work. If you receive the Licensed Work in original or
+modified form from a third party, the terms and conditions set forth in this
+License apply to your use of that work.
+
+Any use of the Licensed Work in violation of this License will automatically
+terminate your rights under this License for the current and all other
+versions of the Licensed Work.
+
+This License does not grant you any right in any trademark or logo of
+Licensor or its affiliates (provided that you may use a trademark or logo of
+Licensor as expressly required by this License).
+
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON
+AN "AS IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS,
+EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND
+TITLE.
+
+MariaDB hereby grants you permission to use this License's text to license
+your works, and to refer to it using the trademark "Business Source License",
+as long as you comply with the Covenants of Licensor below.
+
+Covenants of Licensor
+
+In consideration of the right to use this License's text and the "Business
+Source License" name and trademark, Licensor covenants to MariaDB, and to all
+other recipients of the licensed work to be provided by Licensor:
+
+1. To specify as the Change License the GPL Version 2.0 or any later version,
+   or a license that is compatible with GPL Version 2.0 or a later version,
+   where "compatible" means that software provided under the Change License can
+   be included in a program with software provided under GPL Version 2.0 or a
+   later version. Licensor may specify additional Change Licenses without
+   limitation.
+
+2. To either: (a) specify an additional grant of rights to use that does not
+   impose any additional restriction on the right granted in this License, as
+   the Additional Use Grant; or (b) insert the text "None".
+
+3. To specify a Change Date.
+
+4. Not to modify this License in any other way.
+
+-----------------------------------------------------------------------------
+
+Third-party notices
+
+Versions of this package up to and including 1.277.1 were published under the
+MIT License; those published copies remain governed by the license they were
+distributed under. This package incorporates design and (where noted) prompt
+content adapted from MIT-licensed projects — see NOTICE.md for attributions.

package/README.md

@@ -1,3 +1,99 @@
-# Temporary Holding Version
+# @sema-agent/primitives
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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. 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
+
+```sh
+npm install @sema-agent/primitives
+```
+
+ES modules only (`"type": "module"`), Node >= 20.18.1 where Node is used. One entry, `.`; there are no deep paths.
+
+## Version
+
+`@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
+kinds; whoever resolves it (a deployment's seat, not this package) decides what the name means and whether this
+declaration may use it.
+
+| `kind` | Members | Request surface (`CREDENTIAL_REF_TRUST[kind].request`) |
+| --- | --- | --- |
+| `env` | `headers?`: header name → variable name · `env?`: child variable → variable name (at least one) | `refused` |
+| `vault` | `entry`: a stored credential entry | `own_entry` — only an entry that belongs to the submitting principal |
+| `handle` | `id`: an opaque id the deployment minted | `refused` |
+| `assertion` | `audience`: what a short-lived assertion is requested for | `refused` |
+
+`readCredentialRef(value)` answers `{ ok: true, ref }` with a fresh frozen copy (forward the copy, never the value you
+read), or `{ ok: false, problem }`. Each fault is its own `reason`, and the first one found is the one reported, in this
+order: not a record; `kind` absent, not text or unknown; an extra member; a missing member; a bad value. The reader does not throw: a value whose members cannot be read (a revoked or throwing Proxy) is
+`not_a_record` (or, inside a name map, that map's `bad_value`). With no stack left a valid value may be refused, under any
+reason, and never an invalid one accepted; the call itself may throw a `RangeError` before it is entered, which no function
+can catch.
+
+| `reason` | Meaning |
+| --- | --- |
+| `not_a_record` | not an ordinary record (a primitive, `null`, an array, a class instance, a `Map`, a `Date`), or one whose members cannot be read; an object whose prototype is none or itself has none — the `Object.prototype` of any realm is one — is a record |
+| `unknown_kind` | `kind` is text outside `CREDENTIAL_REF_KINDS` (every spelling the set does not hold: another case, padded, zero-width, full-width, a look-alike letter) |
+| `extra_field` | a member the kind does not have (a member spelled in another case is one) |
+| `missing_field` | `kind`, or a member the kind needs, is absent (for `env`: neither `headers` nor `env`, field `headers\|env`) |
+| `bad_value` | a member of the wrong form (below) |
+
+A member is an own enumerable string-keyed data property. A getter is refused and never called, nothing is read through a
+prototype, a key present with the value `undefined` is a bad value (not an absent member), and a non-enumerable or
+symbol-keyed member is not read and not copied.
+
+`bad_value` is: for `kind`, anything but text; for a text member (`entry`, `id`, `audience`), anything but 1 to
+`CREDENTIAL_REF_TEXT_MAX` (2048) UTF-16 code units with no control, format or line-separator character (C0 and C1,
+zero-width, bidi override, soft hyphen, BOM, U+2028 / U+2029), no default-ignorable, noncharacter or private-use character, no lone surrogate and no leading or trailing white space;
+for a name map (`headers`, `env`), anything but a record of 1 to `CREDENTIAL_REF_MAP_MAX` (64) entries whose names are
+within the grammar (a header name is an HTTP token; a child variable name and every variable name is
+`[A-Za-z_][A-Za-z0-9_]*`) and within the text bound, and — for `headers`, whose names are case-insensitive — in which no
+two names differ only by case. The maps come back frozen and without a prototype: an absent name reads `undefined`, and an
+own `__proto__` name is a plain key. Text is compared as written; nothing is normalised (two spellings of one visible
+string are two entries; visually confusable text — homoglyphs, a braille blank, stacked combining marks — is not judged, and
+an emoji presentation selector or a zero-width joiner is refused, because these members are identifiers, not prose). The text
+bound counts UTF-16 code units (up to 6144 UTF-8 bytes), and the character classes are the
+host's Unicode tables, so two surfaces on engines with different Unicode versions can differ for a recently added character.
+
+```js
+import { readCredentialRef } from "@sema-agent/primitives";
+
+readCredentialRef({ kind: "vault", entry: "github-main" }); // { ok: true, ref: { kind: "vault", entry: "github-main" } }
+readCredentialRef({ kind: "vault2", entry: "x" });          // { ok: false, problem: { reason: "unknown_kind", kind: "vault2" } }
+readCredentialRef({ kind: "handle" });                      // { ok: false, problem: { reason: "missing_field", kind: "handle", field: "id" } }
+readCredentialRef({ kind: "handle", id: "h1", note: "x" }); // { ok: false, problem: { reason: "extra_field", kind: "handle", field: "note" } }
+```
+
+A `kind` or `field` the reader echoes back is the caller's text, cut to 64 characters with control, format and
+line-separator characters and lone surrogates replaced; fence it before rendering it where markup is interpreted. A Proxy's
+own traps (on the value, its maps or its prototype) are the caller's code and run as they would for any property read.
+
+The reader judges shape only: it does not know whether a variable exists, whether an entry belongs to anyone, which header
+names a deployment forbids (the protocol's own names, a principal header), which child variables a declaration may set, or
+whether a reference may reach a destination. Those are the policy of the layer that reads the reference.
+
+`CREDENTIAL_REF_TRUST` has a row for each kind and for nothing else (it has no prototype, so no inherited member answers);
+look a kind up in it only after `readCredentialRef` has accepted the value.
+
+## Exports
+
+Each name below is a runtime value or a type exported from the package root. The root's declarations are the contract; a
+removed or re-kinded export is named as breaking in the `@sema-agent/core` release notes.
+
+| Group | Names |
+| --- | --- |
+| Credential reference | `readCredentialRef` `CREDENTIAL_REF_KINDS` `CREDENTIAL_REF_TRUST` `CREDENTIAL_REF_TEXT_MAX` `CREDENTIAL_REF_MAP_MAX` `CREDENTIAL_REF_PROBLEM_REASONS` |
+| Types | `CredentialRef` `CredentialRefKind` `CredentialRefRequestAdmission` `CredentialRefProblem` `CredentialRefProblemReason` `CredentialRefReading` |

package/dist/credential-ref.d.ts

@@ -0,0 +1,89 @@
+/**
+ * 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>>;
+    readonly env?: Readonly<Record<string, string>>;
+} | {
+    readonly kind: "vault";
+    readonly entry: string;
+} | {
+    readonly kind: "handle";
+    readonly id: string;
+} | {
+    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";
+} | {
+    readonly reason: "unknown_kind";
+    readonly kind: string;
+} | {
+    readonly reason: "missing_field";
+    readonly kind?: CredentialRefKind;
+    readonly field: string;
+} | {
+    readonly reason: "extra_field";
+    readonly kind: CredentialRefKind;
+    readonly field: string;
+} | {
+    readonly reason: "bad_value";
+    readonly kind?: CredentialRefKind;
+    readonly field: string;
+};
+export type CredentialRefReading = {
+    readonly ok: true;
+    readonly ref: CredentialRef;
+} | {
+    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/credential-ref.js

@@ -0,0 +1,125 @@
+export const CREDENTIAL_REF_KINDS = Object.freeze(["env", "vault", "handle", "assertion"]);
+export const CREDENTIAL_REF_TRUST = trustTable();
+function trustTable() {
+    const rows = Object.create(null);
+    rows.env = Object.freeze({ request: "refused" });
+    rows.vault = Object.freeze({ request: "own_entry" });
+    rows.handle = Object.freeze({ request: "refused" });
+    rows.assertion = Object.freeze({ request: "refused" });
+    return Object.freeze(rows);
+}
+export const CREDENTIAL_REF_TEXT_MAX = 2048;
+export const CREDENTIAL_REF_MAP_MAX = 64;
+export const CREDENTIAL_REF_PROBLEM_REASONS = Object.freeze(["not_a_record", "unknown_kind", "missing_field", "extra_field", "bad_value"]);
+const MEMBERS = {
+    env: ["headers", "env"],
+    vault: ["entry"],
+    handle: ["id"],
+    assertion: ["audience"],
+};
+const TEXT_MEMBER = { vault: "entry", handle: "id", assertion: "audience" };
+const HEADER_NAME = /^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/;
+const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const ECHO_MAX = 64;
+const UNSAFE = /[\p{Cc}\p{Cf}\p{Zl}\p{Zp}\p{DI}\p{NChar}\p{Co}\ud800-\udfff]/u;
+const UNSAFE_ALL = new RegExp(UNSAFE.source, "gu");
+const ABSENT = Object.freeze({ found: "absent" });
+const ACCESSOR = Object.freeze({ found: "accessor" });
+const NOT_A_RECORD = Object.freeze({ ok: false, problem: Object.freeze({ reason: "not_a_record" }) });
+function isRecord(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === null || Object.getPrototypeOf(proto) === null;
+}
+function member(record, key) {
+    const descriptor = Object.getOwnPropertyDescriptor(record, key);
+    if (descriptor === undefined || descriptor.enumerable !== true)
+        return ABSENT;
+    return Object.hasOwn(descriptor, "value") ? { found: "value", value: descriptor.value } : ACCESSOR;
+}
+const echo = (text) => text.slice(0, ECHO_MAX).replace(UNSAFE_ALL, "?");
+const refused = (problem) => Object.freeze({ ok: false, problem: Object.freeze(problem) });
+const accepted = (ref) => Object.freeze({ ok: true, ref });
+const isText = (value) => typeof value === "string" && value.length > 0 && value.length <= CREDENTIAL_REF_TEXT_MAX && !UNSAFE.test(value) && value === value.trim();
+const isName = (value, form) => value.length <= CREDENTIAL_REF_TEXT_MAX && form.test(value);
+function nameMap(value, keyForm, foldCase) {
+    try {
+        if (!isRecord(value))
+            return undefined;
+        const names = Object.keys(value);
+        if (names.length === 0 || names.length > CREDENTIAL_REF_MAP_MAX)
+            return undefined;
+        const out = Object.create(null);
+        const folded = new Set();
+        for (const name of names) {
+            const found = member(value, name);
+            if (found.found !== "value" || typeof found.value !== "string")
+                return undefined;
+            if (!isName(name, keyForm) || !isName(found.value, ENV_NAME))
+                return undefined;
+            if (foldCase) {
+                const key = name.toLowerCase();
+                if (folded.has(key))
+                    return undefined;
+                folded.add(key);
+            }
+            out[name] = found.value;
+        }
+        return Object.freeze(out);
+    }
+    catch {
+        return undefined;
+    }
+}
+const mapOf = (found, keyForm, foldCase) => (found.found === "value" ? nameMap(found.value, keyForm, foldCase) : undefined);
+function envRef(record) {
+    const given = { headers: member(record, "headers"), env: member(record, "env") };
+    if (given.headers.found === "absent" && given.env.found === "absent")
+        return refused({ reason: "missing_field", kind: "env", field: "headers|env" });
+    const headers = mapOf(given.headers, HEADER_NAME, true);
+    if (given.headers.found !== "absent" && headers === undefined)
+        return refused({ reason: "bad_value", kind: "env", field: "headers" });
+    const env = mapOf(given.env, ENV_NAME, false);
+    if (given.env.found !== "absent" && env === undefined)
+        return refused({ reason: "bad_value", kind: "env", field: "env" });
+    return accepted(Object.freeze({ kind: "env", ...(headers === undefined ? {} : { headers }), ...(env === undefined ? {} : { env }) }));
+}
+function read(value) {
+    if (!isRecord(value))
+        return NOT_A_RECORD;
+    const named = member(value, "kind");
+    if (named.found === "absent")
+        return refused({ reason: "missing_field", field: "kind" });
+    if (named.found !== "value" || typeof named.value !== "string")
+        return refused({ reason: "bad_value", field: "kind" });
+    const text = named.value;
+    const kind = CREDENTIAL_REF_KINDS.find((k) => k === text);
+    if (kind === undefined)
+        return refused({ reason: "unknown_kind", kind: echo(text) });
+    for (const key of Object.keys(value)) {
+        if (key !== "kind" && !MEMBERS[kind].includes(key))
+            return refused({ reason: "extra_field", kind, field: echo(key) });
+    }
+    if (kind === "env")
+        return envRef(value);
+    const field = TEXT_MEMBER[kind];
+    const found = member(value, field);
+    if (found.found === "absent")
+        return refused({ reason: "missing_field", kind, field });
+    if (found.found !== "value" || !isText(found.value))
+        return refused({ reason: "bad_value", kind, field });
+    if (kind === "vault")
+        return accepted(Object.freeze({ kind, entry: found.value }));
+    if (kind === "handle")
+        return accepted(Object.freeze({ kind, id: found.value }));
+    return accepted(Object.freeze({ kind, audience: found.value }));
+}
+export function readCredentialRef(value) {
+    try {
+        return read(value);
+    }
+    catch {
+        return NOT_A_RECORD;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +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/dist/index.js

@@ -0,0 +1 @@
+export { CREDENTIAL_REF_KINDS, CREDENTIAL_REF_TRUST, CREDENTIAL_REF_TEXT_MAX, CREDENTIAL_REF_MAP_MAX, CREDENTIAL_REF_PROBLEM_REASONS, readCredentialRef, } from "./credential-ref.js";

package/package.json

@@ -1,6 +1,35 @@
 {
   "name": "@sema-agent/primitives",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "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",
+  "license": "BUSL-1.1",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sema-agent/sema-core.git",
+    "directory": "packages/primitives"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20.18.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json && tsc -p tsconfig.json --emitDeclarationOnly --removeComments false"
+  },
+  "gitHead": "05f1a14710d078da0b338fe8712e16f8d790f6bd"
+}