@affiant/core 0.1.0-alpha.0

package/dist/telemetry-keys.d.ts

@@ -0,0 +1,65 @@
+/** One entry in the telemetry-key registry (TL-1). */
+export interface TelemetryKeyEntry {
+    /** The event name. Never renamed, never removed — only deprecated. */
+    readonly key: string;
+    /** The package version this key first shipped in. */
+    readonly since: string;
+    /** What the event means, in one line. */
+    readonly description: string;
+    /**
+     * The attribute names the gate carries on this event. Filled per key by the
+     * pull request that starts emitting it; OpenTelemetry's `gen_ai.*` vocabulary
+     * is used where a name exists there (TL-2).
+     */
+    readonly attributes: readonly string[];
+}
+/** The version of the registry itself. */
+export declare const TELEMETRY_REGISTRY_VERSION = "0.1.0-alpha.0";
+/** Every telemetry key, in registry order. */
+export declare const TELEMETRY_KEYS: readonly [{
+    readonly key: "affidavit.filed";
+    readonly since: "0.1.0-alpha.0";
+    readonly description: "An Affidavit was filed as a Docket entry.";
+    readonly attributes: readonly ["gen_ai.tool.name", "gen_ai.conversation.id", "entry.id", "docket.requirement", "docket.status", "affidavit.field_count", "created"];
+}, {
+    readonly key: "affidavit.refused.substance";
+    readonly since: "0.1.0-alpha.0";
+    readonly description: "A proposal was refused before filing because it swore to nothing (GT-3).";
+    readonly attributes: readonly ["gen_ai.tool.name", "gen_ai.conversation.id", "affidavit.field_count", "reason"];
+}, {
+    readonly key: "coverage.refused";
+    readonly since: "0.1.0-alpha.0";
+    readonly description: "A tool the gate must cover could not be intercepted, or a tool the host declared uncovered produced a proposal (CV-4).";
+    readonly attributes: readonly ["gen_ai.tool.name", "coverage.category", "phase"];
+}, {
+    readonly key: "docket.transition";
+    readonly since: "0.1.0-alpha.0";
+    readonly description: "A Docket entry changed state (DK-1).";
+    readonly attributes: readonly ["entry.id", "gen_ai.conversation.id", "from", "to", "execution", "decision.kind", "attestation.kind", "amended"];
+}, {
+    readonly key: "docket.expired";
+    readonly since: "0.1.0-alpha.0";
+    readonly description: "A pending Docket entry passed its expiry (DK-3).";
+    readonly attributes: readonly ["entry.id"];
+}, {
+    readonly key: "decision.unauthorized";
+    readonly since: "0.1.0-alpha.0";
+    readonly description: "A decision was refused on identity grounds: no resolved principal, another tenant, or the host's authorization port said no (AZ-2).";
+    readonly attributes: readonly ["entry.id", "gen_ai.conversation.id", "reason", "principal.kind", "path"];
+}, {
+    readonly key: "standing-order.fired";
+    readonly since: "0.1.0-alpha.0";
+    readonly description: "A Standing Order policy approved a write with no person present (AZ-1).";
+    readonly attributes: readonly ["policy.id", "policy.version", "entry.id", "risk.score"];
+}, {
+    readonly key: "standing-order.blocked";
+    readonly since: "0.1.0-alpha.0";
+    readonly description: "A Standing Order verdict was not honoured: a proposed field the entity requires had no known value (GT-5), an unbound provenance input (PV-4), or a risk score above the policy's threshold (GT-5). `blocked.reason` is the stable code to alert on - `mandatory-field-empty`, `unbound-declared-input` or `risk-above-threshold`; `reason` is the sentence the reviewer sees on the card and is free to be rephrased.";
+    readonly attributes: readonly ["policy.id", "policy.version", "blocked.reason", "reason", "provenance.field", "provenance.source", "affidavit.empty_mandatory_fields", "risk.score", "risk.threshold"];
+}, {
+    readonly key: "policy.invalid";
+    readonly since: "0.1.0-alpha.0";
+    readonly description: "A host's approval policy broke its own contract: an unusable deadline, or an evaluate that threw (GT-4, CV-1).";
+    readonly attributes: readonly ["policy.id", "policy.version", "option", "reason"];
+}];
+//# sourceMappingURL=telemetry-keys.d.ts.map

package/dist/telemetry-keys.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry-keys.d.ts","sourceRoot":"","sources":["../src/telemetry-keys.ts"],"names":[],"mappings":"AAIA,sDAAsD;AACtD,MAAM,WAAW,iBAAiB;IAChC,sEAAsE;IACtE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,qDAAqD;IACrD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,yCAAyC;IACzC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B;;;;OAIG;IACH,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;CACxC;AAED,0CAA0C;AAC1C,eAAO,MAAM,0BAA0B,kBAAkB,CAAC;AAE1D,8CAA8C;AAC9C,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAgEsB,CAAC"}

package/dist/telemetry-keys.js

@@ -0,0 +1,72 @@
+// GENERATED FILE — DO NOT EDIT BY HAND.
+// Produced by scripts/generate-telemetry-keys.mjs from telemetry-keys.json.
+// To change it: edit telemetry-keys.json, then run `pnpm -C packages/core generate`.
+/** The version of the registry itself. */
+export const TELEMETRY_REGISTRY_VERSION = "0.1.0-alpha.0";
+/** Every telemetry key, in registry order. */
+export const TELEMETRY_KEYS = [
+    /** An Affidavit was filed as a Docket entry. Since 0.1.0-alpha.0. */
+    {
+        key: "affidavit.filed",
+        since: "0.1.0-alpha.0",
+        description: "An Affidavit was filed as a Docket entry.",
+        attributes: ["gen_ai.tool.name", "gen_ai.conversation.id", "entry.id", "docket.requirement", "docket.status", "affidavit.field_count", "created"],
+    },
+    /** A proposal was refused before filing because it swore to nothing (GT-3). Since 0.1.0-alpha.0. */
+    {
+        key: "affidavit.refused.substance",
+        since: "0.1.0-alpha.0",
+        description: "A proposal was refused before filing because it swore to nothing (GT-3).",
+        attributes: ["gen_ai.tool.name", "gen_ai.conversation.id", "affidavit.field_count", "reason"],
+    },
+    /** A tool the gate must cover could not be intercepted, or a tool the host declared uncovered produced a proposal (CV-4). Since 0.1.0-alpha.0. */
+    {
+        key: "coverage.refused",
+        since: "0.1.0-alpha.0",
+        description: "A tool the gate must cover could not be intercepted, or a tool the host declared uncovered produced a proposal (CV-4).",
+        attributes: ["gen_ai.tool.name", "coverage.category", "phase"],
+    },
+    /** A Docket entry changed state (DK-1). Since 0.1.0-alpha.0. */
+    {
+        key: "docket.transition",
+        since: "0.1.0-alpha.0",
+        description: "A Docket entry changed state (DK-1).",
+        attributes: ["entry.id", "gen_ai.conversation.id", "from", "to", "execution", "decision.kind", "attestation.kind", "amended"],
+    },
+    /** A pending Docket entry passed its expiry (DK-3). Since 0.1.0-alpha.0. */
+    {
+        key: "docket.expired",
+        since: "0.1.0-alpha.0",
+        description: "A pending Docket entry passed its expiry (DK-3).",
+        attributes: ["entry.id"],
+    },
+    /** A decision was refused on identity grounds: no resolved principal, another tenant, or the host's authorization port said no (AZ-2). Since 0.1.0-alpha.0. */
+    {
+        key: "decision.unauthorized",
+        since: "0.1.0-alpha.0",
+        description: "A decision was refused on identity grounds: no resolved principal, another tenant, or the host's authorization port said no (AZ-2).",
+        attributes: ["entry.id", "gen_ai.conversation.id", "reason", "principal.kind", "path"],
+    },
+    /** A Standing Order policy approved a write with no person present (AZ-1). Since 0.1.0-alpha.0. */
+    {
+        key: "standing-order.fired",
+        since: "0.1.0-alpha.0",
+        description: "A Standing Order policy approved a write with no person present (AZ-1).",
+        attributes: ["policy.id", "policy.version", "entry.id", "risk.score"],
+    },
+    /** A Standing Order verdict was not honoured: a proposed field the entity requires had no known value (GT-5), an unbound provenance input (PV-4), or a risk score above the policy's threshold (GT-5). `blocked.reason` is the stable code to alert on - `mandatory-field-empty`, `unbound-declared-input` or `risk-above-threshold`; `reason` is the sentence the reviewer sees on the card and is free to be rephrased. Since 0.1.0-alpha.0. */
+    {
+        key: "standing-order.blocked",
+        since: "0.1.0-alpha.0",
+        description: "A Standing Order verdict was not honoured: a proposed field the entity requires had no known value (GT-5), an unbound provenance input (PV-4), or a risk score above the policy's threshold (GT-5). `blocked.reason` is the stable code to alert on - `mandatory-field-empty`, `unbound-declared-input` or `risk-above-threshold`; `reason` is the sentence the reviewer sees on the card and is free to be rephrased.",
+        attributes: ["policy.id", "policy.version", "blocked.reason", "reason", "provenance.field", "provenance.source", "affidavit.empty_mandatory_fields", "risk.score", "risk.threshold"],
+    },
+    /** A host's approval policy broke its own contract: an unusable deadline, or an evaluate that threw (GT-4, CV-1). Since 0.1.0-alpha.0. */
+    {
+        key: "policy.invalid",
+        since: "0.1.0-alpha.0",
+        description: "A host's approval policy broke its own contract: an unusable deadline, or an evaluate that threw (GT-4, CV-1).",
+        attributes: ["policy.id", "policy.version", "option", "reason"],
+    },
+];
+//# sourceMappingURL=telemetry-keys.js.map

package/dist/telemetry-keys.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry-keys.js","sourceRoot":"","sources":["../src/telemetry-keys.ts"],"names":[],"mappings":"AAAA,wCAAwC;AACxC,4EAA4E;AAC5E,qFAAqF;AAkBrF,0CAA0C;AAC1C,MAAM,CAAC,MAAM,0BAA0B,GAAG,eAAe,CAAC;AAE1D,8CAA8C;AAC9C,MAAM,CAAC,MAAM,cAAc,GAAG;IAC5B,qEAAqE;IACrE;QACE,GAAG,EAAE,iBAAiB;QACtB,KAAK,EAAE,eAAe;QACtB,WAAW,EAAE,2CAA2C;QACxD,UAAU,EAAE,CAAC,kBAAkB,EAAE,wBAAwB,EAAE,UAAU,EAAE,oBAAoB,EAAE,eAAe,EAAE,uBAAuB,EAAE,SAAS,CAAC;KAClJ;IACD,oGAAoG;IACpG;QACE,GAAG,EAAE,6BAA6B;QAClC,KAAK,EAAE,eAAe;QACtB,WAAW,EAAE,0EAA0E;QACvF,UAAU,EAAE,CAAC,kBAAkB,EAAE,wBAAwB,EAAE,uBAAuB,EAAE,QAAQ,CAAC;KAC9F;IACD,kJAAkJ;IAClJ;QACE,GAAG,EAAE,kBAAkB;QACvB,KAAK,EAAE,eAAe;QACtB,WAAW,EAAE,wHAAwH;QACrI,UAAU,EAAE,CAAC,kBAAkB,EAAE,mBAAmB,EAAE,OAAO,CAAC;KAC/D;IACD,gEAAgE;IAChE;QACE,GAAG,EAAE,mBAAmB;QACxB,KAAK,EAAE,eAAe;QACtB,WAAW,EAAE,sCAAsC;QACnD,UAAU,EAAE,CAAC,UAAU,EAAE,wBAAwB,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,eAAe,EAAE,kBAAkB,EAAE,SAAS,CAAC;KAC9H;IACD,4EAA4E;IAC5E;QACE,GAAG,EAAE,gBAAgB;QACrB,KAAK,EAAE,eAAe;QACtB,WAAW,EAAE,kDAAkD;QAC/D,UAAU,EAAE,CAAC,UAAU,CAAC;KACzB;IACD,+JAA+J;IAC/J;QACE,GAAG,EAAE,uBAAuB;QAC5B,KAAK,EAAE,eAAe;QACtB,WAAW,EAAE,qIAAqI;QAClJ,UAAU,EAAE,CAAC,UAAU,EAAE,wBAAwB,EAAE,QAAQ,EAAE,gBAAgB,EAAE,MAAM,CAAC;KACvF;IACD,mGAAmG;IACnG;QACE,GAAG,EAAE,sBAAsB;QAC3B,KAAK,EAAE,eAAe;QACtB,WAAW,EAAE,yEAAyE;QACtF,UAAU,EAAE,CAAC,WAAW,EAAE,gBAAgB,EAAE,UAAU,EAAE,YAAY,CAAC;KACtE;IACD,kbAAkb;IAClb;QACE,GAAG,EAAE,wBAAwB;QAC7B,KAAK,EAAE,eAAe;QACtB,WAAW,EAAE,wZAAwZ;QACra,UAAU,EAAE,CAAC,WAAW,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,QAAQ,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,kCAAkC,EAAE,YAAY,EAAE,gBAAgB,CAAC;KACrL;IACD,0IAA0I;IAC1I;QACE,GAAG,EAAE,gBAAgB;QACrB,KAAK,EAAE,eAAe;QACtB,WAAW,EAAE,gHAAgH;QAC7H,UAAU,EAAE,CAAC,WAAW,EAAE,gBAAgB,EAAE,QAAQ,EAAE,QAAQ,CAAC;KAChE;CAC8C,CAAC"}

package/dist/telemetry.d.ts

@@ -0,0 +1,77 @@
+/**
+ * The telemetry port, the event shape, and the versioned key registry.
+ *
+ * **Rules served: TL-1** (the telemetry-key registry is a versioned API),
+ * **TL-2** (where a public standard names the same thing, the registry uses its
+ * name).
+ *
+ * TL-1 in one sentence: *every event and attribute the gate emits is named in a
+ * versioned registry; a key is never renamed, only deprecated.* The registry lives
+ * beside this file as {@link https://github.com/Sakwala/affiant-ts/blob/main/packages/core/telemetry-keys.json `telemetry-keys.json`}
+ * and is generated into `./telemetry-keys.ts` by `scripts/generate-telemetry-keys.mjs`,
+ * the same way `@affiant/contract` generates its schema module — one record a
+ * reader edits, one TypeScript module every runtime can load.
+ *
+ * The registry is what makes the gate's behaviour *observable* rather than
+ * inferable: substance refusal (GT-3), coverage refusal (CV-4) and every Docket
+ * transition (DK-1) are events with fixed names, so an operator can alert on a
+ * refusal rate without reading the gate's source.
+ *
+ * The default port is a no-op. The gate emits whether or not a host is listening,
+ * which is what keeps the emitting call sites honest.
+ *
+ * @packageDocumentation
+ */
+import { TELEMETRY_KEYS } from "./telemetry-keys.js";
+export { TELEMETRY_KEYS, TELEMETRY_REGISTRY_VERSION, type TelemetryKeyEntry, } from "./telemetry-keys.js";
+/**
+ * The name of one event the gate emits. Derived from the registry, so a key that
+ * is not in `telemetry-keys.json` is a compile error at the emitting call site.
+ */
+export type TelemetryKey = (typeof TELEMETRY_KEYS)[number]["key"];
+/** Whether `value` names an event in the registry. */
+export declare function isTelemetryKey(value: unknown): value is TelemetryKey;
+/**
+ * The attributes carried on one event.
+ *
+ * Scalars only, and `null` rather than `undefined` for "no value" — the same rule
+ * the wire types follow, so an event survives a JSON round trip into whatever the
+ * host's collector is without a shape change. Never put a field value, an utterance
+ * or a principal id in here: telemetry is operational, and the audit record is the
+ * Affidavit.
+ */
+export type TelemetryAttributes = {
+    readonly [name: string]: string | number | boolean | null;
+};
+/** One thing that happened, named by the registry. */
+export interface TelemetryEvent {
+    /** Which event this is. */
+    readonly key: TelemetryKey;
+    /**
+     * When it happened, as an ISO 8601 instant in UTC — read from the gate's
+     * `Clock` port, never from an ambient timer.
+     */
+    readonly at: string;
+    /** The attributes for this event. `{}` when there are none. */
+    readonly attributes: TelemetryAttributes;
+}
+/**
+ * Where the gate's events go. Supplied by the host; the gate never chooses a sink.
+ *
+ * `emit` is synchronous and must not throw: an event is a side channel, and a
+ * collector that is down cannot be allowed to fail a write. Buffer or drop inside
+ * the implementation.
+ */
+export interface TelemetryPort {
+    /** Record one event. Must not throw. */
+    emit(event: TelemetryEvent): void;
+}
+/**
+ * The port used when a host supplies none. Drops every event.
+ *
+ * It exists so the gate's emitting call sites are unconditional — no
+ * `telemetry?.emit(...)` at each site, and no branch that could quietly stop
+ * emitting.
+ */
+export declare const noopTelemetry: TelemetryPort;
+//# sourceMappingURL=telemetry.d.ts.map

package/dist/telemetry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry.d.ts","sourceRoot":"","sources":["../src/telemetry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAErD,OAAO,EACL,cAAc,EACd,0BAA0B,EAC1B,KAAK,iBAAiB,GACvB,MAAM,qBAAqB,CAAC;AAE7B;;;GAGG;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,CAAC,CAAC,KAAK,CAAC,CAAC;AAElE,sDAAsD;AACtD,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,YAAY,CAIpE;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,mBAAmB,GAAG;IAChC,QAAQ,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC;CAC3D,CAAC;AAEF,sDAAsD;AACtD,MAAM,WAAW,cAAc;IAC7B,2BAA2B;IAC3B,QAAQ,CAAC,GAAG,EAAE,YAAY,CAAC;IAC3B;;;OAGG;IACH,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,+DAA+D;IAC/D,QAAQ,CAAC,UAAU,EAAE,mBAAmB,CAAC;CAC1C;AAED;;;;;;GAMG;AACH,MAAM,WAAW,aAAa;IAC5B,wCAAwC;IACxC,IAAI,CAAC,KAAK,EAAE,cAAc,GAAG,IAAI,CAAC;CACnC;AAED;;;;;;GAMG;AACH,eAAO,MAAM,aAAa,EAAE,aAI3B,CAAC"}

package/dist/telemetry.js

@@ -0,0 +1,43 @@
+/**
+ * The telemetry port, the event shape, and the versioned key registry.
+ *
+ * **Rules served: TL-1** (the telemetry-key registry is a versioned API),
+ * **TL-2** (where a public standard names the same thing, the registry uses its
+ * name).
+ *
+ * TL-1 in one sentence: *every event and attribute the gate emits is named in a
+ * versioned registry; a key is never renamed, only deprecated.* The registry lives
+ * beside this file as {@link https://github.com/Sakwala/affiant-ts/blob/main/packages/core/telemetry-keys.json `telemetry-keys.json`}
+ * and is generated into `./telemetry-keys.ts` by `scripts/generate-telemetry-keys.mjs`,
+ * the same way `@affiant/contract` generates its schema module — one record a
+ * reader edits, one TypeScript module every runtime can load.
+ *
+ * The registry is what makes the gate's behaviour *observable* rather than
+ * inferable: substance refusal (GT-3), coverage refusal (CV-4) and every Docket
+ * transition (DK-1) are events with fixed names, so an operator can alert on a
+ * refusal rate without reading the gate's source.
+ *
+ * The default port is a no-op. The gate emits whether or not a host is listening,
+ * which is what keeps the emitting call sites honest.
+ *
+ * @packageDocumentation
+ */
+import { TELEMETRY_KEYS } from "./telemetry-keys.js";
+export { TELEMETRY_KEYS, TELEMETRY_REGISTRY_VERSION, } from "./telemetry-keys.js";
+/** Whether `value` names an event in the registry. */
+export function isTelemetryKey(value) {
+    return (typeof value === "string" && TELEMETRY_KEYS.some((entry) => entry.key === value));
+}
+/**
+ * The port used when a host supplies none. Drops every event.
+ *
+ * It exists so the gate's emitting call sites are unconditional — no
+ * `telemetry?.emit(...)` at each site, and no branch that could quietly stop
+ * emitting.
+ */
+export const noopTelemetry = {
+    emit() {
+        // Intentionally empty: the default sink drops events.
+    },
+};
+//# sourceMappingURL=telemetry.js.map

package/dist/telemetry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry.js","sourceRoot":"","sources":["../src/telemetry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAErD,OAAO,EACL,cAAc,EACd,0BAA0B,GAE3B,MAAM,qBAAqB,CAAC;AAQ7B,sDAAsD;AACtD,MAAM,UAAU,cAAc,CAAC,KAAc;IAC3C,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ,IAAI,cAAc,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAE,KAAK,CAAC,GAAc,KAAK,KAAK,CAAC,CAC7F,CAAC;AACJ,CAAC;AAwCD;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,aAAa,GAAkB;IAC1C,IAAI;QACF,sDAAsD;IACxD,CAAC;CACF,CAAC"}