@phosphorco/bb-jev 0.0.0-stage → 0.1.0-alpha.1

package/CONTRACT.md

@@ -0,0 +1,17 @@
+# Shared JEV transport v1
+
+This package owns bounded JSON DTOs and intended-owner RPC adapters. It owns no credential, storage, inference policy, admission gate, timer or retry engine. Root imports Zod only; `/bb` has SDK type imports only; `/testing` drives real adopter ports with caller-supplied inert work.
+
+Topics (`jev-topics`) is the first explicit connection owner. Its existing secret setting remains local. `sharedJevDescribeV1(null)` advertises protocol `bb-jev`, versions, owner/configured metadata, the nonsecret setting field/source, supported named work and limits. A consumer uses listed plugin discovery for that explicit owner; absence/disabled/incompatibility is an operational error, never permission to scan credentials or switch owners.
+
+`sharedJevSubmitV1` takes version1, exact namespace/operationId, consumer/work kind/opaque attribution, finite JSON wire, absolute deadline and response bound. Inputs are strict. A complete canonical SHA256 input fingerprint binds wire, work, attribution, operation, deadline and budgets. No URL/header/key parameter exists. Owner storage must reserve that immutable request before work and persist effect-possible before its fixed JEV HTTP POST. Same operation+input returns retained facts, changed input conflicts. Invoked or uncertain work must never be automatically relaunched, including after process/plugin restart. An interrupted effect-possible row becomes uncertain. Consumer policy/budget/evaluation ledgers remain consumer-owned.
+
+`sharedJevLookupV1` takes version+exact operation and returns null or current record. Results are additive at evolving object boundaries. Opaque attribution/response JSON remains exact. States distinguish positive not-invoked from possible invocation, succeeded transport, failed transport and uncertain effects. Success is transport evidence, never semantic policy approval. Usage preserves provider-reported token counts and opaque reported cost (or null); missing/invalid usage remains explicit. No price or token estimate is invented. Raw response and bounded HTTP error context are retained, masking only the exact owner credential. Work attribution identifies MR admission/suite and their attempt/partition separately from Topics assessment work.
+
+Package caps: request1MiB, raw response1MiB, response envelope1MiB+64KiB, describe16KiB, JSON depth48, max absolute execution budget60s and4 physical unsettled calls per client lane (submit, ordinary read, reconciliation read; maximum12 RPCs). Owner advertises/enforces its physical limit independently and retains a slot until HTTP/body work actually settles. Abort/timeout only fences a local observation; it does not establish non-execution. The adapter attempts at most ONE independent bounded lookup after failed submit, using separate reconciliation capacity so saturated writes cannot starve the first reconciliation wave. If that finite read capacity is also occupied, it refuses locally and retains unknown; it never retries submit. A lookup failure/null remains unknown.
+
+No cancel-write method is provided in v1: cancelling an observer or MR evaluation cannot undo an already invoked HTTP call. The service owns its deadline and disposal abort. Late terminal HTTP observations may settle the owner's transport journal, while a retired MR assessment remains fenced by its own ledger.
+
+Provider must preserve existing Topics scopes/assessment behavior and serve shared named work independently of an assessment profile. Initial named work is `message-rules.admission` and `message-rules.suite`. Dedicated MR override remains an explicit consumer selection and is not a service credential source.
+
+Proof layers: package emitted/packed tests, real owner SQLite+RPC conformance, actual MR adopter ledger tests and loaded cross-plugin inference are separate. No package test establishes loaded runtime, native admission, provider execution or billing correctness.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Phosphor
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,9 @@
-# Temporary Holding Version
+# @phosphorco/bb-jev
 
-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.
+Versioned shared JEV transport without exporting credentials. The connection owner keeps its key and durable operation journal; consumers keep their own policy, budgets and evaluation ledgers.
+
+- Root: strict request/additive result schemas, JSON bounds and fingerprints.
+- `/bb`: owner registration and an explicit-owner client with one lookup after unknown submit, no write retry.
+- `/testing`: anchored immutable-operation conformance for real adopter handlers.
+
+See [CONTRACT.md](CONTRACT.md) for exact methods, limits, ownership and uncertainty semantics. Version0.1.0-alpha.1 is a prerelease; source checks do not establish registry or live adoption.

package/dist/bb.js

@@ -0,0 +1,155 @@
+// src/bb.ts
+import { z } from "zod";
+import * as p from "./protocol.js";
+function sdkSchema(schema) {
+  return { "~standard": {
+    version: 1,
+    vendor: "bb-jev",
+    jsonSchema: {
+      input: () => schema.toJSONSchema({ io: "input", unrepresentable: "any" }),
+      output: () => schema.toJSONSchema({ io: "output", unrepresentable: "any" })
+    },
+    validate(value) {
+      const parsed = schema.safeParse(value);
+      return parsed.success ? { value: parsed.data } : { issues: parsed.error.issues.map((issue) => ({ message: issue.message, path: issue.path.map((k) => typeof k === "symbol" ? String(k) : k) })) };
+    }
+  } };
+}
+function registerJevOwner(bb, port) {
+  bb.rpc.register({
+    [p.METHODS.describe]: { input: sdkSchema(z.null()), output: sdkSchema(p.DescribeSchema) },
+    [p.METHODS.submit]: { input: sdkSchema(p.SubmitSchema), output: sdkSchema(p.RecordSchema) },
+    [p.METHODS.lookup]: { input: sdkSchema(p.LookupSchema), output: sdkSchema(p.RecordSchema.nullable()) }
+  }, {
+    [p.METHODS.describe]: async () => p.decode(p.DescribeSchema, await port.describe(), p.LIMITS.describeBytes),
+    [p.METHODS.submit]: async (input) => {
+      const captured = p.decode(p.SubmitSchema, JSON.parse(p.canonical(input, p.LIMITS.requestBytes)), p.LIMITS.requestBytes);
+      const record = await p.decodeRecord(captured, await port.submit(captured));
+      if (!record)
+        throw Error("JEV owner omitted submitted operation");
+      return record;
+    },
+    [p.METHODS.lookup]: async (input) => p.decodeRecord(input, await port.lookup(input))
+  }, { experimental_discoverable: true });
+}
+
+class JevCallError extends Error {
+  outcome;
+  original;
+  constructor(outcome, message, original) {
+    super(message);
+    this.outcome = outcome;
+    this.original = original;
+    this.name = "JevCallError";
+  }
+}
+function bounded(run, ms, outer) {
+  const ctrl = new AbortController;
+  return new Promise((resolve, reject) => {
+    let done = false;
+    const finish = (fn) => {
+      if (done)
+        return;
+      done = true;
+      clearTimeout(timer);
+      outer?.removeEventListener("abort", abort);
+      fn();
+    };
+    const abort = () => {
+      ctrl.abort();
+      finish(() => reject(Error("JEV observation cancelled; remote work may continue")));
+    };
+    const timer = setTimeout(() => {
+      ctrl.abort();
+      finish(() => reject(Error("JEV observation deadline; remote work may continue")));
+    }, Math.max(1, ms));
+    outer?.addEventListener("abort", abort, { once: true });
+    if (outer?.aborted) {
+      abort();
+      return;
+    }
+    Promise.resolve().then(() => run(ctrl.signal)).then((v) => finish(() => resolve(v)), (e) => finish(() => reject(e)));
+  });
+}
+function createJevClient(sdk, ownerPluginId = p.DEFAULT_OWNER) {
+  const physical = { submit: 0, read: 0, reconcile: 0 };
+  async function call(method, input, ms, signal, reconcile = false) {
+    const lane = method === p.METHODS.submit ? "submit" : reconcile ? "reconcile" : "read";
+    if (physical[lane] >= p.LIMITS.concurrency)
+      throw Error("JEV client unsettled-call capacity exceeded");
+    return bounded((s) => {
+      if (physical[lane] >= p.LIMITS.concurrency)
+        throw Error("JEV client unsettled-call capacity exceeded");
+      physical[lane]++;
+      let pending;
+      try {
+        pending = Promise.resolve(sdk.plugins.callRpc({ pluginId: ownerPluginId, method, input, outputSchema: z.unknown(), signal: s }));
+      } catch (e) {
+        physical[lane]--;
+        throw e;
+      }
+      pending.then(() => physical[lane]--, () => physical[lane]--);
+      return pending;
+    }, ms, signal);
+  }
+  async function lookup(operation, signal, reconcile = false) {
+    const input = p.LookupSchema.parse({ version: 1, operation });
+    try {
+      return await p.decodeRecord(input, await call(p.METHODS.lookup, input, 2000, signal, reconcile));
+    } catch (e) {
+      throw new JevCallError("read-failed", "Shared JEV operation lookup failed", e);
+    }
+  }
+  return {
+    ownerPluginId,
+    async describe(signal) {
+      try {
+        const listed = await bounded((s) => sdk.plugins.list({ signal: s }), 2000, signal);
+        if (!listed.plugins.some((plugin) => plugin.id === ownerPluginId && plugin.status === "running"))
+          throw Error(`Shared JEV owner ${ownerPluginId} is missing, disabled or not running`);
+        const raw = await call(p.METHODS.describe, null, 2000, signal);
+        const envelope = p.decode(p.DescribeEnvelopeSchema, raw, p.LIMITS.describeBytes);
+        if (envelope.protocol !== p.PROTOCOL || !envelope.versions.includes(1))
+          throw Error("Shared JEV protocol version is incompatible");
+        const value = p.decode(p.DescribeSchema, raw, p.LIMITS.describeBytes);
+        if (value.ownerPluginId !== ownerPluginId || value.source.ownerPluginId !== ownerPluginId)
+          throw Error("Shared JEV connection owner mismatch");
+        return value;
+      } catch (e) {
+        throw new JevCallError("incompatible", e instanceof Error ? e.message : String(e), e);
+      }
+    },
+    lookup,
+    async submit(raw, signal) {
+      let input;
+      try {
+        input = p.decode(p.SubmitSchema, JSON.parse(p.canonical(raw, p.LIMITS.requestBytes)), p.LIMITS.requestBytes);
+        if (signal?.aborted || input.deadlineAt <= Date.now())
+          throw Error("JEV deadline/cancellation before submit");
+      } catch (e) {
+        throw new JevCallError("not-invoked", "Shared JEV request refused before submit", e);
+      }
+      try {
+        const value = await p.decodeRecord(input, await call(p.METHODS.submit, input, Math.min(p.LIMITS.deadlineMs, input.deadlineAt - Date.now()) + 250, signal));
+        if (!value)
+          throw Error("JEV owner returned no operation");
+        return value;
+      } catch (e) {
+        try {
+          const retained = await lookup(input.operation, undefined, true);
+          if (retained) {
+            const checked = await p.decodeRecord(input, retained);
+            if (checked)
+              return checked;
+          }
+        } catch {}
+        throw new JevCallError("unknown", "Shared JEV submit outcome unknown; retain operation and reconcile without resending", e);
+      }
+    }
+  };
+}
+export {
+  registerJevOwner,
+  createJevClient,
+  JevCallError
+};

package/dist/protocol.js

@@ -0,0 +1,168 @@
+// src/protocol.ts
+import { z } from "zod";
+var PROTOCOL = "bb-jev";
+var VERSION = 1;
+var DEFAULT_OWNER = "jev-topics";
+var METHODS = Object.freeze({ describe: "sharedJevDescribeV1", submit: "sharedJevSubmitV1", lookup: "sharedJevLookupV1" });
+var LIMITS = Object.freeze({ requestBytes: 1048576, responseBytes: 1114112, wireResponseBytes: 1048576, describeBytes: 16384, depth: 48, deadlineMs: 60000, concurrency: 4 });
+function canonical(value, maxBytes = LIMITS.responseBytes) {
+  const seen = new Set;
+  let spent = 0;
+  const charge = (n) => {
+    spent += n;
+    if (spent > maxBytes)
+      throw Error("JSON byte budget exceeded");
+  };
+  const leaf = (v) => {
+    const text = JSON.stringify(v);
+    charge(new TextEncoder().encode(text).byteLength);
+    return text;
+  };
+  function visit(v, depth) {
+    if (depth > LIMITS.depth)
+      throw Error("JSON depth exceeded");
+    if (v === null || typeof v === "boolean" || typeof v === "string")
+      return leaf(v);
+    if (typeof v === "number" && Number.isFinite(v))
+      return leaf(v);
+    if (!v || typeof v !== "object" || seen.has(v))
+      throw Error("Expected finite acyclic JSON");
+    seen.add(v);
+    try {
+      if (Array.isArray(v)) {
+        if (Reflect.ownKeys(v).length !== v.length + 1)
+          throw Error("Sparse or decorated JSON array");
+        charge(2 + Math.max(0, v.length - 1));
+        const elements = [];
+        for (let i = 0;i < v.length; i++) {
+          const d = Object.getOwnPropertyDescriptor(v, String(i));
+          if (!d || !("value" in d))
+            throw Error("JSON array accessor");
+          elements.push(visit(d.value, depth + 1));
+        }
+        return "[" + elements.join(",") + "]";
+      }
+      if (Object.getPrototypeOf(v) !== Object.prototype && Object.getPrototypeOf(v) !== null)
+        throw Error("Expected plain JSON object");
+      if (Reflect.ownKeys(v).some((k) => typeof k !== "string"))
+        throw Error("JSON symbol key");
+      const keys = Object.keys(v).sort();
+      charge(2 + Math.max(0, keys.length - 1));
+      return "{" + keys.map((k) => {
+        const descriptor = Object.getOwnPropertyDescriptor(v, k);
+        if (!descriptor || !("value" in descriptor) || !descriptor.enumerable)
+          throw Error("JSON accessor/property");
+        charge(new TextEncoder().encode(JSON.stringify(k)).byteLength + 1);
+        return JSON.stringify(k) + ":" + visit(descriptor.value, depth + 1);
+      }).join(",") + "}";
+    } finally {
+      seen.delete(v);
+    }
+  }
+  const bytes = visit(value, 0);
+  if (new TextEncoder().encode(bytes).byteLength > maxBytes)
+    throw Error("JSON byte budget exceeded");
+  return bytes;
+}
+async function fingerprint(value) {
+  const bytes = new TextEncoder().encode(canonical(value, LIMITS.requestBytes));
+  const hash = await globalThis.crypto.subtle.digest("SHA-256", bytes);
+  return "sha256:" + Array.from(new Uint8Array(hash), (x) => x.toString(16).padStart(2, "0")).join("");
+}
+var JsonSchema = z.custom((value) => {
+  try {
+    canonical(value);
+    return true;
+  } catch {
+    return false;
+  }
+}, "Expected bounded finite plain JSON");
+var id = z.string().min(1).max(256).regex(/^[^\p{Cc}]+$/u);
+var OperationKeySchema = z.strictObject({ namespace: id, operationId: id });
+var SubmitSchema = z.strictObject({
+  version: z.literal(1),
+  operation: OperationKeySchema,
+  work: z.strictObject({ consumerPluginId: id, kind: id, attribution: JsonSchema }),
+  wire: JsonSchema,
+  deadlineAt: z.number().int().positive().max(Number.MAX_SAFE_INTEGER),
+  maxResponseBytes: z.number().int().min(1024).max(LIMITS.wireResponseBytes)
+});
+var LookupSchema = z.strictObject({ version: z.literal(1), operation: OperationKeySchema });
+var SourceSchema = z.looseObject({ ownerPluginId: id, kind: z.literal("plugin-setting"), field: id });
+var UsageSchema = z.discriminatedUnion("status", [
+  z.looseObject({ status: z.literal("reported"), inputTokens: z.number().int().nonnegative(), outputTokens: z.number().int().nonnegative(), cost: JsonSchema }),
+  z.looseObject({ status: z.enum(["missing", "invalid"]), cost: JsonSchema })
+]);
+var RecordSchema = z.looseObject({
+  version: z.literal(1),
+  operation: z.looseObject(OperationKeySchema.shape),
+  requestFingerprint: z.string().regex(/^sha256:[a-f0-9]{64}$/),
+  work: z.looseObject(SubmitSchema.shape.work.shape),
+  state: z.enum(["not-invoked", "effect-possible", "succeeded", "failed", "uncertain"]),
+  invoked: z.boolean(),
+  source: SourceSchema,
+  createdAt: z.number().int().nonnegative(),
+  settledAt: z.number().int().nonnegative().nullable(),
+  latencyMs: z.number().nonnegative().nullable(),
+  httpStatus: z.number().int().min(100).max(599).nullable(),
+  response: JsonSchema,
+  usage: UsageSchema,
+  error: z.looseObject({ code: id, message: z.string().max(8192) }).nullable()
+}).superRefine((v, c) => {
+  if (v.state === "not-invoked" && v.invoked)
+    c.addIssue({ code: "custom", message: "Not-invoked cannot claim invocation" });
+  if (v.state !== "not-invoked" && !v.invoked)
+    c.addIssue({ code: "custom", message: "Possible invocation must be retained" });
+  if (v.state === "effect-possible" && v.settledAt !== null)
+    c.addIssue({ code: "custom", message: "Active work cannot be settled" });
+  if (v.state !== "effect-possible" && v.settledAt === null)
+    c.addIssue({ code: "custom", message: "Final observation requires settlement time" });
+  if (v.state === "succeeded" && (v.error !== null || v.response === null))
+    c.addIssue({ code: "custom", message: "Success requires a response and no transport error" });
+});
+var DescribeEnvelopeSchema = z.looseObject({ protocol: z.string(), versions: z.array(z.number().int()).max(16) });
+var DescribeSchema = z.looseObject({
+  protocol: z.literal(PROTOCOL),
+  versions: z.array(z.number().int()).max(16),
+  ownerPluginId: id,
+  configured: z.boolean(),
+  source: SourceSchema,
+  workKinds: z.array(id).max(32),
+  limits: z.looseObject({ requestBytes: z.number().int().positive(), responseBytes: z.number().int().positive(), deadlineMs: z.number().int().positive(), concurrency: z.number().int().positive() })
+});
+function decode(schema, value, maxBytes = LIMITS.responseBytes) {
+  canonical(value, maxBytes);
+  return schema.parse(value);
+}
+async function decodeRecord(input, value) {
+  if (value === null)
+    return null;
+  const record = decode(RecordSchema, value);
+  if (record.operation.namespace !== input.operation.namespace || record.operation.operationId !== input.operation.operationId)
+    throw Error("JEV response operation mismatch");
+  if ("wire" in input && record.requestFingerprint !== await fingerprint(input))
+    throw Error("JEV response immutable request mismatch");
+  if ("wire" in input && canonical({ consumerPluginId: record.work.consumerPluginId, kind: record.work.kind, attribution: record.work.attribution }) !== canonical(input.work))
+    throw Error("JEV response work mismatch");
+  return record;
+}
+export {
+  fingerprint,
+  decodeRecord,
+  decode,
+  canonical,
+  VERSION,
+  UsageSchema,
+  SubmitSchema,
+  SourceSchema,
+  RecordSchema,
+  PROTOCOL,
+  OperationKeySchema,
+  METHODS,
+  LookupSchema,
+  LIMITS,
+  JsonSchema,
+  DescribeSchema,
+  DescribeEnvelopeSchema,
+  DEFAULT_OWNER
+};

package/dist/testing.js

@@ -0,0 +1,27 @@
+// src/testing.ts
+import { canonical, decodeRecord, fingerprint } from "./protocol.js";
+async function runJevConformance(port, input) {
+  const initial = await decodeRecord(input, await port.submit(input));
+  if (!initial || initial.requestFingerprint !== await fingerprint(input))
+    throw Error("Submitted operation not anchored");
+  const anchor = (record) => canonical({ operation: { namespace: record.operation.namespace, operationId: record.operation.operationId }, requestFingerprint: record.requestFingerprint, work: { consumerPluginId: record.work.consumerPluginId, kind: record.work.kind, attribution: record.work.attribution }, createdAt: record.createdAt, source: { ownerPluginId: record.source.ownerPluginId, kind: record.source.kind, field: record.source.field } });
+  const frozen = anchor(initial);
+  const replay = await decodeRecord(input, await port.submit(input));
+  if (!replay || anchor(replay) !== frozen)
+    throw Error("Same operation replay drifted");
+  const lookup = await decodeRecord(input, await port.lookup(input.operation));
+  if (!lookup || anchor(lookup) !== frozen)
+    throw Error("Operation lookup drifted");
+  let conflict = false;
+  try {
+    await port.submit({ ...input, work: { ...input.work, kind: input.work.kind + "-changed" } });
+  } catch {
+    conflict = true;
+  }
+  if (!conflict)
+    throw Error("Changed immutable request did not conflict");
+  return { cases: ["request-anchored", "immutable-replay", "exact-lookup", "changed-request-conflict"] };
+}
+export {
+  runJevConformance
+};

package/dist/types/bb.d.ts

@@ -0,0 +1,65 @@
+import type { BbPluginApi } from '@get-bb/plugin-sdk';
+import { z } from 'zod';
+import * as p from './protocol.js';
+export interface OwnerPort {
+    describe(): p.Description | Promise<p.Description>;
+    submit(input: p.Submit): Promise<p.OperationRecord>;
+    lookup(input: z.infer<typeof p.LookupSchema>): p.OperationRecord | null | Promise<p.OperationRecord | null>;
+}
+export declare function registerJevOwner(bb: Pick<BbPluginApi, 'rpc'>, port: OwnerPort): void;
+export declare class JevCallError extends Error {
+    readonly outcome: 'not-invoked' | 'unknown' | 'read-failed' | 'incompatible';
+    readonly original?: unknown | undefined;
+    constructor(outcome: 'not-invoked' | 'unknown' | 'read-failed' | 'incompatible', message: string, original?: unknown | undefined);
+}
+/** Select one explicit owner. No secret discovery, write retry, or availability polling. */
+export declare function createJevClient(sdk: Pick<BbPluginApi['sdk'], 'plugins'>, ownerPluginId?: string): {
+    ownerPluginId: string;
+    describe(signal?: AbortSignal): Promise<p.Description>;
+    lookup: (operation: p.OperationKey, signal?: AbortSignal, reconcile?: boolean) => Promise<{
+        [x: string]: unknown;
+        version: 1;
+        operation: {
+            [x: string]: unknown;
+            namespace: string;
+            operationId: string;
+        };
+        requestFingerprint: string;
+        work: {
+            [x: string]: unknown;
+            consumerPluginId: string;
+            kind: string;
+            attribution: p.Json;
+        };
+        state: "not-invoked" | "effect-possible" | "succeeded" | "failed" | "uncertain";
+        invoked: boolean;
+        source: {
+            [x: string]: unknown;
+            ownerPluginId: string;
+            kind: "plugin-setting";
+            field: string;
+        };
+        createdAt: number;
+        settledAt: number | null;
+        latencyMs: number | null;
+        httpStatus: number | null;
+        response: p.Json;
+        usage: {
+            [x: string]: unknown;
+            status: "reported";
+            inputTokens: number;
+            outputTokens: number;
+            cost: p.Json;
+        } | {
+            [x: string]: unknown;
+            status: "missing" | "invalid";
+            cost: p.Json;
+        };
+        error: {
+            [x: string]: unknown;
+            code: string;
+            message: string;
+        } | null;
+    } | null>;
+    submit(raw: p.Submit, signal?: AbortSignal): Promise<p.OperationRecord>;
+};

package/dist/types/protocol.d.ts

@@ -0,0 +1,146 @@
+import { z } from 'zod';
+export declare const PROTOCOL: "bb-jev";
+export declare const VERSION: 1;
+export declare const DEFAULT_OWNER = "jev-topics";
+export declare const METHODS: Readonly<{
+    describe: "sharedJevDescribeV1";
+    submit: "sharedJevSubmitV1";
+    lookup: "sharedJevLookupV1";
+}>;
+export declare const LIMITS: Readonly<{
+    requestBytes: 1048576;
+    responseBytes: 1114112;
+    wireResponseBytes: 1048576;
+    describeBytes: 16384;
+    depth: 48;
+    deadlineMs: 60000;
+    concurrency: 4;
+}>;
+export type Json = null | boolean | number | string | Json[] | {
+    [key: string]: Json;
+};
+/** Validate finite plain JSON before decoding; never invoke toJSON or silently drop undefined. */
+export declare function canonical(value: unknown, maxBytes?: number): string;
+export declare function fingerprint(value: unknown): Promise<string>;
+export declare const JsonSchema: z.ZodType<Json>;
+export declare const OperationKeySchema: z.ZodObject<{
+    namespace: z.ZodString;
+    operationId: z.ZodString;
+}, z.core.$strict>;
+export type OperationKey = z.infer<typeof OperationKeySchema>;
+export declare const SubmitSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    operation: z.ZodObject<{
+        namespace: z.ZodString;
+        operationId: z.ZodString;
+    }, z.core.$strict>;
+    work: z.ZodObject<{
+        consumerPluginId: z.ZodString;
+        kind: z.ZodString;
+        attribution: z.ZodType<Json, unknown, z.core.$ZodTypeInternals<Json, unknown>>;
+    }, z.core.$strict>;
+    wire: z.ZodType<Json, unknown, z.core.$ZodTypeInternals<Json, unknown>>;
+    deadlineAt: z.ZodNumber;
+    maxResponseBytes: z.ZodNumber;
+}, z.core.$strict>;
+export type Submit = z.infer<typeof SubmitSchema>;
+export declare const LookupSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    operation: z.ZodObject<{
+        namespace: z.ZodString;
+        operationId: z.ZodString;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export declare const SourceSchema: z.ZodObject<{
+    ownerPluginId: z.ZodString;
+    kind: z.ZodLiteral<"plugin-setting">;
+    field: z.ZodString;
+}, z.core.$loose>;
+export declare const UsageSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    status: z.ZodLiteral<"reported">;
+    inputTokens: z.ZodNumber;
+    outputTokens: z.ZodNumber;
+    cost: z.ZodType<Json, unknown, z.core.$ZodTypeInternals<Json, unknown>>;
+}, z.core.$loose>, z.ZodObject<{
+    status: z.ZodEnum<{
+        missing: "missing";
+        invalid: "invalid";
+    }>;
+    cost: z.ZodType<Json, unknown, z.core.$ZodTypeInternals<Json, unknown>>;
+}, z.core.$loose>], "status">;
+export declare const RecordSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    operation: z.ZodObject<{
+        namespace: z.ZodString;
+        operationId: z.ZodString;
+    }, z.core.$loose>;
+    requestFingerprint: z.ZodString;
+    work: z.ZodObject<{
+        consumerPluginId: z.ZodString;
+        kind: z.ZodString;
+        attribution: z.ZodType<Json, unknown, z.core.$ZodTypeInternals<Json, unknown>>;
+    }, z.core.$loose>;
+    state: z.ZodEnum<{
+        "not-invoked": "not-invoked";
+        "effect-possible": "effect-possible";
+        succeeded: "succeeded";
+        failed: "failed";
+        uncertain: "uncertain";
+    }>;
+    invoked: z.ZodBoolean;
+    source: z.ZodObject<{
+        ownerPluginId: z.ZodString;
+        kind: z.ZodLiteral<"plugin-setting">;
+        field: z.ZodString;
+    }, z.core.$loose>;
+    createdAt: z.ZodNumber;
+    settledAt: z.ZodNullable<z.ZodNumber>;
+    latencyMs: z.ZodNullable<z.ZodNumber>;
+    httpStatus: z.ZodNullable<z.ZodNumber>;
+    response: z.ZodType<Json, unknown, z.core.$ZodTypeInternals<Json, unknown>>;
+    usage: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        status: z.ZodLiteral<"reported">;
+        inputTokens: z.ZodNumber;
+        outputTokens: z.ZodNumber;
+        cost: z.ZodType<Json, unknown, z.core.$ZodTypeInternals<Json, unknown>>;
+    }, z.core.$loose>, z.ZodObject<{
+        status: z.ZodEnum<{
+            missing: "missing";
+            invalid: "invalid";
+        }>;
+        cost: z.ZodType<Json, unknown, z.core.$ZodTypeInternals<Json, unknown>>;
+    }, z.core.$loose>], "status">;
+    error: z.ZodNullable<z.ZodObject<{
+        code: z.ZodString;
+        message: z.ZodString;
+    }, z.core.$loose>>;
+}, z.core.$loose>;
+export type OperationRecord = z.infer<typeof RecordSchema>;
+export declare const DescribeEnvelopeSchema: z.ZodObject<{
+    protocol: z.ZodString;
+    versions: z.ZodArray<z.ZodNumber>;
+}, z.core.$loose>;
+export declare const DescribeSchema: z.ZodObject<{
+    protocol: z.ZodLiteral<"bb-jev">;
+    versions: z.ZodArray<z.ZodNumber>;
+    ownerPluginId: z.ZodString;
+    configured: z.ZodBoolean;
+    source: z.ZodObject<{
+        ownerPluginId: z.ZodString;
+        kind: z.ZodLiteral<"plugin-setting">;
+        field: z.ZodString;
+    }, z.core.$loose>;
+    workKinds: z.ZodArray<z.ZodString>;
+    limits: z.ZodObject<{
+        requestBytes: z.ZodNumber;
+        responseBytes: z.ZodNumber;
+        deadlineMs: z.ZodNumber;
+        concurrency: z.ZodNumber;
+    }, z.core.$loose>;
+}, z.core.$loose>;
+export type Description = z.infer<typeof DescribeSchema>;
+export declare function decode<T>(schema: z.ZodType<T>, value: unknown, maxBytes?: number): T;
+/** Bind every response to the requested operation; immutable request identity cannot drift on replay. */
+export declare function decodeRecord(input: Submit | {
+    operation: OperationKey;
+}, value: unknown): Promise<OperationRecord | null>;

package/dist/types/testing.d.ts

@@ -0,0 +1,9 @@
+import { type Submit, type OperationRecord } from './protocol.js';
+export interface ConformancePort {
+    submit(input: Submit): Promise<OperationRecord>;
+    lookup(operation: Submit['operation']): Promise<OperationRecord | null>;
+}
+/** Real adopter callers supply an inert transport. The kit makes no inference itself. */
+export declare function runJevConformance(port: ConformancePort, input: Submit): Promise<{
+    cases: string[];
+}>;

package/package.json

@@ -1,6 +1,58 @@
 {
   "name": "@phosphorco/bb-jev",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0-alpha.1",
+  "type": "module",
+  "license": "MIT",
+  "description": "Bounded shared JEV transport operations for independently installed BB plugins.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/phosphorco/bb-community-plugins.git",
+    "directory": "packages/bb-jev"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/types/protocol.d.ts",
+      "import": "./dist/protocol.js"
+    },
+    "./bb": {
+      "types": "./dist/types/bb.d.ts",
+      "import": "./dist/bb.js"
+    },
+    "./testing": {
+      "types": "./dist/types/testing.d.ts",
+      "import": "./dist/testing.js"
+    }
+  },
+  "files": [
+    "dist/",
+    "README.md",
+    "CONTRACT.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "tag": "next"
+  },
+  "dependencies": {
+    "zod": "4.6.7"
+  },
+  "devDependencies": {
+    "bun": "1.3.14",
+    "typescript": "5.9.3",
+    "@get-bb/plugin-sdk": "0.6.52"
+  },
+  "scripts": {
+    "build": "bun tools/build.mjs && tsc -p tsconfig.declarations.json",
+    "typecheck": "tsc --noEmit",
+    "test": "npm run build && node --test test/*.test.mjs",
+    "test:packed-consumer": "node tools/packed-consumer.mjs"
+  },
+  "peerDependencies": {
+    "@get-bb/plugin-sdk": ">=0.6.52 <0.7.0"
+  },
+  "peerDependenciesMeta": {
+    "@get-bb/plugin-sdk": {
+      "optional": true
+    }
+  }
+}