@yaklabs-ai/plugin-sdk 0.8.4 → 0.8.5

package/README.md

@@ -13,7 +13,7 @@ it under the name your plugin code actually imports:
 ```json
 {
   "dependencies": {
-    "@kay/plugin-sdk": "npm:@yaklabs-ai/plugin-sdk@^0.8.4"
+    "@kay/plugin-sdk": "npm:@yaklabs-ai/plugin-sdk@^0.8.5"
   }
 }
 ```

package/THIRD-PARTY-INVENTORY.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "package": "@yaklabs-ai/plugin-sdk",
-  "version": "0.8.4",
+  "version": "0.8.5",
   "target": "npm",
   "firstPartyLicense": "MIT",
   "bundled": [

package/dist/jev.d.ts

@@ -0,0 +1,76 @@
+import { Questions } from '@typesafe-ai/sdk';
+import { SystemOneRequest } from '@typesafe-ai/sdk';
+import { SystemOneResult } from '@typesafe-ai/sdk';
+import { TypeSafeClient } from '@typesafe-ai/sdk';
+import { Usage } from '@typesafe-ai/sdk';
+
+/**
+ * The `withJev` a host with no Jev lane binds: `use` is never called, no client is ever built,
+ * and no network is ever touched. It keeps the cancellation contract identical to the real
+ * wrapper's so a caller's `signal`/`deadlineAt` handling does not change with host composition.
+ *
+ * Deliberately here rather than in the runtime: this is the DEFAULT for the SDK's own host
+ * factory, which cannot import the runtime uphill. The runtime also delegates fallback execution
+ * here, so both paths share cancellation, deadline enforcement, and cleanup.
+ */
+export declare function createFallbackOnlyWithJev(): WithJev;
+
+export { Questions }
+
+export { SystemOneRequest }
+
+export { SystemOneResult }
+
+export { TypeSafeClient }
+
+export { Usage }
+
+/**
+ * Run `use` against a live Jev client, falling back to `fallback` whenever Jev cannot serve the
+ * call. The wrapper exists so a feature can ASK for a typed decision without ever depending on
+ * one: `fallback` is required, and it runs whenever no host-managed key is saved,
+ * the user has not granted `jev.use`, the branch exceeds its budget, `use` throws, or
+ * `use` declines by returning `undefined`. With valid options, this rejects on an explicit
+ * `signal` abort, reaching `deadlineAt`, or `fallback` itself throwing.
+ *
+ * ALWAYS PRESENT on the plugin API, on every host. A host that composed no Jev lane binds
+ * {@link createFallbackOnlyWithJev}, so a caller never branches on availability — branching is
+ * exactly how a fallback gets skipped.
+ *
+ * `jev` is the vendor's own `TypeSafeClient`, configured with the host's default model and base
+ * URL. Native `request.model` overrides remain supported. It
+ * is valid only for the duration of the callback: a reference retained past `use`'s scope is
+ * refused at the transport, and an in-flight request is aborted when the call stops waiting.
+ * The callback itself is ABANDONED, not interrupted — a host cannot stop arbitrary JavaScript
+ * that is already running, so `use` must not perform side effects it would mind completing
+ * unobserved. The same applies to a running fallback: abort/deadline stops waiting for it but
+ * cannot interrupt its JavaScript.
+ */
+export declare type WithJev = <T>(
+/** Return `undefined` to decline (the fallback runs). A feature whose real result can itself be
+ *  `undefined` should return `null` or its own wrapper type instead. */
+use: (jev: TypeSafeClient) => T | undefined | PromiseLike<T | undefined>, 
+/** Required. The behaviour the feature has without Jev. */
+fallback: () => T | PromiseLike<T>, options?: WithJevOptions) => Promise<T>;
+
+/** Per-call knobs for {@link WithJev}. Every field is optional; the host applies its own default
+ *  budget when none is given, so the Jev branch is never unbounded. */
+export declare interface WithJevOptions {
+    /**
+     * Explicit cancellation. Always propagates as a rejection; never substituted with `fallback`,
+     * because an aborted call means "stop", not "use the cheaper path".
+     */
+    readonly signal?: AbortSignal;
+    /** Bounds the Jev branch alone, measured from the call. */
+    readonly timeoutMs?: number;
+    /**
+     * Absolute epoch-ms hard deadline for the WHOLE call, `fallback` included. A deadline already
+     * passed rejects (like `signal`); one still ahead derives the Jev branch's budget from it and
+     * keeps a small reserve so `fallback` has a window to run.
+     */
+    readonly deadlineAt?: number;
+    /** Attribution slug for host usage accounting. Never sent to Jev. */
+    readonly purpose?: string;
+}
+
+export { }

package/dist/jev.js

@@ -0,0 +1,63 @@
+// packages/plugin-sdk/dist/jev.js
+function createFallbackOnlyWithJev() {
+  return async (_use, fallback, options = {}) => {
+    if (typeof fallback !== "function") {
+      throw new TypeError("withJev requires a `fallback` function as its second argument.");
+    }
+    const { signal, deadlineAt } = options;
+    if (deadlineAt !== void 0 && !Number.isFinite(deadlineAt)) {
+      throw new TypeError("withJev's `deadlineAt` must be a finite epoch-ms timestamp.");
+    }
+    const assertWithinBoundaries = () => {
+      if (signal?.aborted === true) {
+        throw signal.reason ?? new DOMException("Aborted", "AbortError");
+      }
+      if (deadlineAt !== void 0 && Date.now() >= deadlineAt) {
+        throw new Error("withJev's deadline has passed.");
+      }
+    };
+    assertWithinBoundaries();
+    let timer;
+    let onAbort;
+    const stopped = new Promise((_resolve, reject) => {
+      if (signal !== void 0) {
+        onAbort = () => reject(signal.reason ?? new DOMException("Aborted", "AbortError"));
+        signal.addEventListener("abort", onAbort, { once: true });
+      }
+      if (deadlineAt !== void 0) {
+        const checkDeadline = () => {
+          const remaining = deadlineAt - Date.now();
+          if (remaining <= 0) {
+            reject(new Error("withJev's deadline has passed."));
+          } else {
+            timer = setTimeout(checkDeadline, Math.min(remaining, 2147483647));
+          }
+        };
+        checkDeadline();
+      }
+    });
+    try {
+      const result = await Promise.race([
+        Promise.resolve().then(() => {
+          assertWithinBoundaries();
+          return fallback();
+        }),
+        stopped
+      ]);
+      assertWithinBoundaries();
+      return result;
+    } catch (error) {
+      assertWithinBoundaries();
+      throw error;
+    } finally {
+      if (timer !== void 0)
+        clearTimeout(timer);
+      if (signal !== void 0 && onAbort !== void 0) {
+        signal.removeEventListener("abort", onAbort);
+      }
+    }
+  };
+}
+export {
+  createFallbackOnlyWithJev
+};

package/dist/signals.d.ts

@@ -0,0 +1,360 @@
+import type { ChoiceResponse } from '@typesafe-ai/sdk';
+import type { NoulResponse } from '@typesafe-ai/sdk';
+import type { Questions } from '@typesafe-ai/sdk';
+import type { ScoreResponse } from '@typesafe-ai/sdk';
+
+export { ChoiceResponse }
+
+/**
+ * The `signals` a host with no Jev lane or no signals store binds: `observe` never touches the
+ * network, answers `invalid` for an input that breaks the recorded-name grammar exactly as a
+ * real host would, and otherwise `unavailable` with `stored: false`; both reads answer
+ * `unavailable` with reason `no-store`. So a caller's result handling does not change with host
+ * composition.
+ */
+export declare function createFallbackOnlySignals(): KayAppSignals;
+
+/**
+ * The `invalid` observation `observe` answers when a name in `input` breaks the recorded-name
+ * grammar, or `undefined` when every name can be recorded. A reader later types these names into
+ * an address or a `where` filter, so a row that broke the grammar would be unaddressable or
+ * unfilterable forever: the grammars are on {@link KayAppSignalsDetectorInput},
+ * {@link KayAppSignalSource}, and {@link KayAppSignalsObserveInput}. Checked first, before any
+ * digest, grant, store, or Jev call, by the host and by {@link createFallbackOnlySignals} alike.
+ */
+export declare function invalidObservation(input: KayAppSignalsObserveInput): KayAppSignalObservation | undefined;
+
+/** One stored signal: the answers exactly as Jev gave them, and where the observed turn is. */
+export declare interface KayAppSignal {
+    /** Recording order: a higher id was recorded later. */
+    readonly id: number;
+    readonly detector: KayAppSignalsDetectorRef & {
+        readonly pluginId: string;
+    };
+    readonly source: KayAppSignalSource;
+    readonly recordedAtMs: number;
+    /** Keyed by question name, full probability distributions included. */
+    readonly answers: Readonly<Record<string, NoulResponse | ChoiceResponse | ScoreResponse>>;
+    /** The inference that produced the answers; absent when the host recorded only part of it. */
+    readonly inference?: {
+        readonly model: string;
+        readonly inputTokens: number;
+        readonly outputTokens: number;
+        readonly tookMs: number;
+    };
+    /** Digest of the state Jev read: re-derive the state from the transcript and compare. */
+    readonly inputDigest: string;
+}
+
+/** One version of one detector, under one rubric, as the catalog lists it. */
+export declare interface KayAppSignalDetector {
+    readonly pluginId: string;
+    readonly id: string;
+    readonly version: string;
+    /**
+     * The questions never change under one digest, so cache them by it. Two digests under one
+     * version mean the rubric was edited without a version bump.
+     */
+    readonly rubricDigest: string;
+    readonly questions: Questions;
+    readonly firstRecordedAtMs: number;
+    readonly lastRecordedAtMs: number;
+}
+
+/**
+ * The result of one observe call. `status` is the only field a caller must switch on:
+ *
+ * - `classified`: Jev answered; `answers`, `model`, and `usage` are the vendor's verbatim
+ *   response, and `stored` says whether the row landed in the durable store.
+ * - `unavailable`: Jev could not answer (no key, refused grant, timeout, vendor error, or a
+ *   malformed response). `reason` names the host's classification; no row is written, so the
+ *   same input can be observed again later without a conflict.
+ * - `invalid`: the input breaks the recorded-name grammar (see {@link invalidObservation}), and
+ *   `reason` says which name and why. The caller's mistake, not the environment's: Jev is never
+ *   called, no row is written, and the same input is refused again. `detector` and `source`
+ *   echo only the detector id and version and the session and entry ids, each empty when the
+ *   input did not carry it as a string.
+ *
+ * A repeat call over the same (plugin, detector, version, session, entry, input digest) returns
+ * the ALREADY-STORED row with `deduplicated: true` and never calls Jev again: replay is free.
+ */
+export declare interface KayAppSignalObservation {
+    readonly id?: number | undefined;
+    readonly status: "classified" | "unavailable" | "invalid";
+    readonly detector: KayAppSignalsDetectorRef;
+    readonly source: KayAppSignalSource;
+    readonly answers?: Record<string, unknown> | undefined;
+    readonly model?: string | undefined;
+    readonly usage?: {
+        readonly inputTokens: number;
+        readonly outputTokens: number;
+    } | undefined;
+    readonly tookMs?: number | undefined;
+    readonly reason?: string | undefined;
+    /** True when the row landed in the durable store; false when the host composed no store. */
+    readonly stored: boolean;
+    /** True when this call returned an already-stored row instead of running inference. */
+    readonly deduplicated: boolean;
+    readonly inputDigest: string;
+    readonly recordedAtMs: number;
+}
+
+/** One page of signals, oldest recorded first. */
+export declare interface KayAppSignalPage {
+    readonly signals: readonly KayAppSignal[];
+    /**
+     * Pass as `after` to continue, now or on a later run: the next read returns only signals
+     * recorded after this page, including any a detector backfilled since. Absent only when this
+     * page is empty, which means nothing newer than `after` exists right now; keep the cursor you
+     * already have.
+     */
+    readonly nextCursor?: string;
+}
+
+/**
+ * The plugin's signal door. `observe` runs the fused inference-and-record step; `list` and
+ * `listDetectors` read recorded signals back. The plugin id is stamped by the host at the
+ * boundary and is never a parameter.
+ *
+ * Reads are checked against the `signals.read` claim on every call, and a granted plugin reads
+ * EVERY plugin's signals, not only its own.
+ */
+export declare interface KayAppSignals {
+    observe(input: KayAppSignalsObserveInput): Promise<KayAppSignalObservation>;
+    /**
+     * Every detector that has recorded a signal: one entry per version and rubric, each with its
+     * questions. Call it once and cache questions by `rubricDigest`; result pages never repeat
+     * them.
+     */
+    listDetectors(): Promise<KayAppSignalsRead<{
+        readonly detectors: readonly KayAppSignalDetector[];
+    }>>;
+    /** Stored signals for one session, or for one detector across sessions, oldest first. */
+    list(query: KayAppSignalsQuery): Promise<KayAppSignalsRead<KayAppSignalPage>>;
+}
+
+/**
+ * One condition on one question's stored answer. Jev answers are probabilities, so each kind of
+ * question gets the comparison that makes sense for it:
+ *
+ * - `yes`: a yes/no question's probability of yes, from 0 to 1.
+ * - `choice`: a choice question's chosen label is one of these, with at least `minConfidence`
+ *   (0 to 1) when given. At most {@link MAX_CHOICE_LABELS} labels, repeats included; a repeat
+ *   changes nothing else.
+ * - `score`: a score question's expected score.
+ *
+ * The filter is refused as `invalid`, never answered with a silently empty page, when no
+ * version of the detector in the query's scope asks the question with the filter's kind, or when
+ * a `choice` filter names a label the rubric does not offer. A filter matches only rows whose
+ * stored answer to the question is of its own kind, so rows from a version where the question
+ * is absent or asks another kind never match; pin `version` to read one version.
+ */
+export declare type KayAppSignalsAnswerFilter = {
+    readonly question: string;
+    readonly yes: KayAppSignalsRange;
+} | {
+    readonly question: string;
+    readonly choice: readonly string[];
+    readonly minConfidence?: number;
+} | {
+    readonly question: string;
+    readonly score: KayAppSignalsRange;
+};
+
+/**
+ * One detector as the recording plugin names it. The host never interprets these values;
+ * `id` + `version` are the plugin's half of the versioning contract that lets a consumer tell
+ * one rubric's answers from another's. The other half, the rubric digest, is the host's: it is
+ * computed from the `questions` actually sent, so a plugin can neither mis-stamp it nor forget
+ * it, and a rubric edit that did not bump `version` still shows up as a digest change.
+ */
+export declare interface KayAppSignalsDetectorInput {
+    /**
+     * Stable identifier, e.g. `memory-curator-gate`: a lowercase slug (a-z and 0-9 in words joined
+     * by single hyphens), at most 64 characters, plugin-scoped. It becomes a `signals://` path
+     * segment.
+     */
+    readonly id: string;
+    /**
+     * The version the plugin bumps when its rubric's meaning changes, e.g. `v1.0.0`: letters and
+     * digits in parts joined by single `.`, `-`, or `_`, at most 64 characters.
+     */
+    readonly version: string;
+}
+
+/**
+ * A detector a read names. `pluginId` is required because detector ids are unique only within
+ * the plugin that records them. Omit `version` to read every version; each returned signal
+ * carries the version it was recorded under.
+ */
+export declare interface KayAppSignalsDetectorMatch {
+    readonly pluginId: string;
+    readonly id: string;
+    readonly version?: string;
+}
+
+/** One detector's signals across every session, optionally in a turn-time window and filtered. */
+export declare interface KayAppSignalsDetectorQuery {
+    readonly detector: KayAppSignalsDetectorMatch;
+    /** Never both anchors: a detector query reads that detector across every session. */
+    readonly sessionId?: never;
+    /**
+     * Epoch ms, inclusive, on TURN time: when the observed turn settled, or, for a signal whose
+     * recorder did not know that, when it was recorded. A detector backfilled over old history
+     * therefore places each signal on the day its turn happened. A whole number from 0 to
+     * {@link SIGNAL_TIME_MAX_MS}.
+     */
+    readonly since?: number;
+    /** Epoch ms, exclusive, on turn time, in the same range as `since`. */
+    readonly until?: number;
+    /** Every filter must hold. At most 20. */
+    readonly where?: readonly KayAppSignalsAnswerFilter[];
+    /** A `nextCursor` from an earlier page: only signals recorded after it are returned. */
+    readonly after?: string;
+    /** Default 200, at most 1000 (a larger value is lowered to 1000). */
+    readonly limit?: number;
+}
+
+/** A detector as a recorded row names it: the plugin's id and version plus the host's digest. */
+export declare interface KayAppSignalsDetectorRef extends KayAppSignalsDetectorInput {
+    /**
+     * `sha256:<hex>` over the questions serialised with sorted keys, stamped by the host. Empty
+     * when nothing was stamped: on a fallback-only host, and on an `invalid` observation.
+     */
+    readonly rubricDigest: string;
+}
+
+export declare interface KayAppSignalsObserveInput {
+    readonly detector: KayAppSignalsDetectorInput;
+    readonly source: KayAppSignalSource;
+    /**
+     * The exact state to send, already shaped by the caller (a turn packet, a window of messages,
+     * or anything else). NOT stored: the row keeps its digest, and a reader re-derives it from the
+     * transcript the source points at. So the projection must be a pure function of the
+     * transcript and the detector version, or the row's evidence cannot be reproduced.
+     */
+    readonly state: unknown;
+    /**
+     * The typed questions to answer, as the vendor SDK accepts them. Stored once per digest. A
+     * rubric asks 1 to 64 questions. Each name is an identifier (letters, digits, and `_`, not
+     * starting with a digit), at most 64 characters, because a reader types it into a `where`
+     * filter. A choice question offers at most {@link MAX_CHOICE_LABELS} labels, each 1 to 64
+     * characters with no `,`, `@`, or control or invisible character (`\p{C}`), and no whitespace
+     * but single spaces between words, so a reader can copy it back exactly from rendered text.
+     */
+    readonly questions: Questions;
+    readonly options?: WithJevOptions;
+}
+
+/**
+ * Where the observation came from: a pointer into the transcript, which is the only thing the
+ * row keeps of the state. The settle anchor is the entry the session event named; it may be a
+ * post-run bookkeeping entry (a settle event points at the run's last entry, not necessarily
+ * the opening message), so the packet helper folds it back to the turn it follows and reports
+ * that turn's opener here.
+ */
+export declare interface KayAppSignalSource {
+    /**
+     * The session, settle, and opener ids are each 1 to 256 characters with no whitespace, `/`,
+     * `?`, `#`, or control or invisible character (`\p{C}`), so each can be named in an address
+     * and renders exactly as stored.
+     */
+    readonly sessionId: string;
+    /** The settle anchor: a member of the dedupe key. */
+    readonly entryId: string;
+    /** The message that opened the observed turn, when the caller's projection has one. */
+    readonly openerEntryId?: string;
+    /**
+     * The daemon run that produced the settle: 1 to 256 characters with no control character.
+     * No reader types it into an address or a filter, so nothing else about it is constrained.
+     */
+    readonly runId?: string;
+    /**
+     * Epoch ms of the settle anchor, when the caller knows it: a whole number from 0 to
+     * {@link SIGNAL_TIME_MAX_MS}.
+     */
+    readonly occurredAtMs?: number;
+}
+
+/**
+ * Every read names one session or one detector. There is no read across every detector at
+ * once, because its cost grows with every detector anyone adds; the host refuses a query that
+ * names neither, or both, at runtime as well as in the type.
+ */
+export declare type KayAppSignalsQuery = KayAppSignalsSessionQuery | KayAppSignalsDetectorQuery;
+
+/** A numeric range. An absent bound is open; a present bound is inclusive. */
+export declare interface KayAppSignalsRange {
+    readonly atLeast?: number;
+    readonly atMost?: number;
+}
+
+/**
+ * The outcome of a read. Like `observe`, a read never rejects while the plugin is enabled; a
+ * handle kept after the plugin is disabled throws synchronously instead.
+ *
+ * - `ok`: the result.
+ * - `unavailable`: this host cannot serve reads right now. `reason` is `not-granted` (the
+ *   `signals.read` claim was refused), `no-store` (this host records no signals), or
+ *   `store-unavailable` (the store failed). Asking again later is reasonable.
+ * - `invalid`: the host refused the query itself, and `reason` says why in plain words: for
+ *   example a question the detector's rubric does not ask, a filter of the wrong kind for its
+ *   question, or a cursor this host did not issue. The same query will be refused again.
+ */
+export declare type KayAppSignalsRead<T> = ({
+    readonly status: "ok";
+} & T) | {
+    readonly status: "unavailable";
+    readonly reason: string;
+} | {
+    readonly status: "invalid";
+    readonly reason: string;
+};
+
+/** One session's signals: every detector's, or only the detectors named. */
+export declare interface KayAppSignalsSessionQuery {
+    readonly sessionId: string;
+    /** Never both anchors: a session query names detectors through `detectors`. */
+    readonly detector?: never;
+    /** Omit for every detector. At most 100, and never empty. */
+    readonly detectors?: readonly KayAppSignalsDetectorMatch[];
+    /** A `nextCursor` from an earlier page: only signals recorded after it are returned. */
+    readonly after?: string;
+    /** Default 200, at most 1000 (a larger value is lowered to 1000). */
+    readonly limit?: number;
+}
+
+/** The most labels a recorded choice question may offer, and so the most one filter names. */
+export declare const MAX_CHOICE_LABELS = 64;
+
+export { NoulResponse }
+
+export { ScoreResponse }
+
+/**
+ * The largest epoch-millisecond time a `Date` can hold (about the year 275,760). A time outside
+ * 0 to this bound has no date to show, so neither `observe` nor a read window accepts one.
+ */
+export declare const SIGNAL_TIME_MAX_MS = 8640000000000000;
+
+/** Per-call knobs for {@link WithJev}. Every field is optional; the host applies its own default
+ *  budget when none is given, so the Jev branch is never unbounded. */
+declare interface WithJevOptions {
+    /**
+     * Explicit cancellation. Always propagates as a rejection; never substituted with `fallback`,
+     * because an aborted call means "stop", not "use the cheaper path".
+     */
+    readonly signal?: AbortSignal;
+    /** Bounds the Jev branch alone, measured from the call. */
+    readonly timeoutMs?: number;
+    /**
+     * Absolute epoch-ms hard deadline for the WHOLE call, `fallback` included. A deadline already
+     * passed rejects (like `signal`); one still ahead derives the Jev branch's budget from it and
+     * keeps a small reserve so `fallback` has a window to run.
+     */
+    readonly deadlineAt?: number;
+    /** Attribution slug for host usage accounting. Never sent to Jev. */
+    readonly purpose?: string;
+}
+
+export { }

package/dist/signals.js

@@ -0,0 +1,132 @@
+// packages/plugin-sdk/dist/signals.js
+import { z } from "zod";
+function createFallbackOnlySignals() {
+  const noStore = { status: "unavailable", reason: "no-store" };
+  return {
+    observe: (input) => Promise.resolve(invalidObservation(input) ?? {
+      status: "unavailable",
+      reason: "no-jev-lane",
+      detector: { ...input.detector, rubricDigest: "" },
+      source: input.source,
+      stored: false,
+      deduplicated: false,
+      inputDigest: "",
+      recordedAtMs: Date.now()
+    }),
+    listDetectors: () => Promise.resolve(noStore),
+    list: () => Promise.resolve(noStore)
+  };
+}
+var SIGNAL_TIME_MAX_MS = 864e13;
+var MAX_CHOICE_LABELS = 64;
+var MAX_NAME = 64;
+var MAX_POINTER = 256;
+var MAX_QUESTIONS = 64;
+var DETECTOR_ID = /^[a-z0-9]+(?:-[a-z0-9]+)*$/u;
+var VERSION = /^[A-Za-z0-9]+(?:[._-][A-Za-z0-9]+)*$/u;
+var QUESTION_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/u;
+var POINTER = /^[^\s\p{C}/?#]+$/u;
+var LABEL = /^[^\s,@\p{C}]+(?: [^\s,@\p{C}]+)*$/u;
+var RUN_ID = /^\P{Cc}+$/u;
+var POINTER_RULE = `1 to ${MAX_POINTER} characters with no whitespace, \`/\`, \`?\`, \`#\`, or control or invisible character`;
+var ObserveShape = z.looseObject({
+  detector: z.looseObject({ id: z.string(), version: z.string() }),
+  source: z.looseObject({
+    sessionId: z.string(),
+    entryId: z.string(),
+    openerEntryId: z.string().optional(),
+    runId: z.string().optional(),
+    occurredAtMs: z.unknown().optional()
+  }),
+  questions: z.record(z.string(), z.unknown())
+});
+var ChoiceQuestion = z.looseObject({
+  type: z.literal("choice"),
+  criteria: z.record(z.string(), z.unknown())
+});
+var fits = (value, grammar) => value.length <= MAX_NAME && grammar.test(value);
+var quoted = (value) => JSON.stringify(value.length > 40 ? `${value.slice(0, 40)}\u2026` : value).replace(/(?! )[\s\p{C}]/gu, (char) => `\\u${char.codePointAt(0).toString(16).padStart(4, "0")}`);
+function grammarProblem(input) {
+  const shape = ObserveShape.safeParse(input);
+  if (!shape.success) {
+    const field = shape.error.issues[0]?.path.join(".") ?? "";
+    return field === "" ? "`observe` takes an object with `detector`, `source`, `state`, and `questions`." : `\`${field}\` is missing or has the wrong type.`;
+  }
+  const { detector, source, questions } = shape.data;
+  if (!fits(detector.id, DETECTOR_ID)) {
+    return "`detector.id` must be a lowercase slug of at most 64 characters: a-z and 0-9 in words joined by single hyphens.";
+  }
+  if (!fits(detector.version, VERSION)) {
+    return "`detector.version` must be at most 64 characters: letters and digits in parts joined by single `.`, `-`, or `_`.";
+  }
+  for (const [field, grammar, rule] of [
+    ["sessionId", POINTER, POINTER_RULE],
+    ["entryId", POINTER, POINTER_RULE],
+    ["openerEntryId", POINTER, POINTER_RULE],
+    [
+      "runId",
+      RUN_ID,
+      `1 to ${MAX_POINTER} characters with no control character`
+    ]
+  ]) {
+    const id = source[field];
+    if (id !== void 0 && !(id.length <= MAX_POINTER && grammar.test(id))) {
+      return `\`source.${field}\` must be ${rule}.`;
+    }
+  }
+  const occurredAtMs = source.occurredAtMs;
+  if (occurredAtMs !== void 0 && !(typeof occurredAtMs === "number" && Number.isSafeInteger(occurredAtMs) && occurredAtMs >= 0 && occurredAtMs <= SIGNAL_TIME_MAX_MS)) {
+    return `\`source.occurredAtMs\` must be whole epoch milliseconds from 0 to ${SIGNAL_TIME_MAX_MS}.`;
+  }
+  const names = Object.keys(questions);
+  if (names.length === 0 || names.length > MAX_QUESTIONS) {
+    return `\`questions\` must ask 1 to ${MAX_QUESTIONS} questions.`;
+  }
+  for (const name of names) {
+    if (!fits(name, QUESTION_NAME)) {
+      return `The question name ${quoted(name)} must be an identifier of at most 64 characters: letters, digits, and \`_\`, not starting with a digit.`;
+    }
+    const choice = ChoiceQuestion.safeParse(questions[name]);
+    if (!choice.success)
+      continue;
+    const labels = Object.keys(choice.data.criteria);
+    if (labels.length > MAX_CHOICE_LABELS) {
+      return `The choice question \`${name}\` offers ${labels.length} labels; at most ${MAX_CHOICE_LABELS}.`;
+    }
+    const bad = labels.find((label) => !fits(label, LABEL));
+    if (bad !== void 0) {
+      return `The choice question \`${name}\` offers the label ${quoted(bad)}, which a \`where\` filter cannot name: a label is 1 to 64 characters with no \`,\`, \`@\`, or control or invisible character, and no whitespace but single spaces between words.`;
+    }
+  }
+  return void 0;
+}
+var EchoText = z.string().catch("");
+var Echo = z.object({
+  detector: z.object({ id: EchoText, version: EchoText }).catch({ id: "", version: "" }),
+  source: z.object({ sessionId: EchoText, entryId: EchoText }).catch({ sessionId: "", entryId: "" })
+}).catch({
+  detector: { id: "", version: "" },
+  source: { sessionId: "", entryId: "" }
+});
+function invalidObservation(input) {
+  const reason = grammarProblem(input);
+  if (reason === void 0)
+    return void 0;
+  const { detector, source } = Echo.parse(input);
+  return {
+    status: "invalid",
+    reason,
+    detector: { ...detector, rubricDigest: "" },
+    source,
+    stored: false,
+    deduplicated: false,
+    inputDigest: "",
+    recordedAtMs: Date.now()
+  };
+}
+export {
+  MAX_CHOICE_LABELS,
+  SIGNAL_TIME_MAX_MS,
+  createFallbackOnlySignals,
+  invalidObservation
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yaklabs-ai/plugin-sdk",
-  "version": "0.8.4",
+  "version": "0.8.5",
   "description": "The Kay plugin SDK — types and helpers for authoring a Kay directory plugin.",
   "author": "YakLabs",
   "type": "module",
@@ -25,6 +25,14 @@
       "types": "./dist/disclosure.d.ts",
       "default": "./dist/disclosure.js"
     },
+    "./jev": {
+      "types": "./dist/jev.d.ts",
+      "default": "./dist/jev.js"
+    },
+    "./signals": {
+      "types": "./dist/signals.d.ts",
+      "default": "./dist/signals.js"
+    },
     "./phase-shift": {
       "types": "./dist/phase-shift.d.ts",
       "default": "./dist/phase-shift.js"