@phosphorco/bb-inbox-rows 0.0.0-stage → 0.1.1

package/CONTRACT.md

@@ -0,0 +1,17 @@
+# Inbox rows v1
+
+Inbox owns root/visibility/archive/lifecycle validation, identity binding, indexed source reads and canonical sender/body models. The package owns bounded DTOs, fixed RPC methods, injected registration/client adapters and conformance. A host owns discovery (listed plugins plus fixed describe), one shared hydration resource, navigation, selection, fallback, error isolation, freshness and close cancellation. No feature storage, React renderer or polling is provided here.
+
+`METHODS.describe = inboxRowsV1Describe`, null input. Negotiate the tolerant protocol/versions envelope before parsing v1 details. `METHODS.read = inboxRowsV1Read` takes `{version:1, occurrences:[{key,threadId}], archiveMode:'active'|'include-archived', viewAs?:string|null}`. There are 1–16 occurrences; duplicate keys are invalid, distinct keys for the same thread are allowed. Omitted/null viewAs selects the actual actor through Inbox's existing identity binding; a non-null subject selects a read lens, never a new actor.
+
+Response `{version:1, ownerKey:string|null, revision:string, rows:[...]}` echoes the resolved subject and source snapshot revision. Every requested occurrence appears exactly once with the same thread ID. A ready row is `{key,threadId,state:'ready',revision,data:RowData}`; an unavailable row has `state:'unavailable',reason` (not-found/not-top-level/excluded/timeout/source-error/oversize). Ready data threadId must match. Non-null requested subject must echo exactly. Missing and unsolicited occurrences fail the client boundary.
+
+RowData contains `v:1,threadId,title,groupPath,tags,tagOverflow,owners,ownerOverflow,ownerOverflowLabel,participants,participantOverflow,senderDescription,status:{tone,label},time:{at,text,title}`. Face entries contain `{key,name:string|null,imageUrl:string|null,label,external:boolean}`. Ordered owner and participant arrays each contain at most two portraits. Missing owner profiles retain a visible unknown owner. Owners are always shown in hosted search. Owner keys are removed from participants; participant duplicates collapse in canonical order. Overflow represents remaining canonical identities. Attribution and recent-sender descriptions follow native Inbox. Status is the thread's own lifecycle/attention, never a family aggregate. Time includes an absolute epoch ms and preformatted text; inert bodies schedule no updates.
+
+Inputs are strict at all boundaries. Outputs are additive at every evolving object boundary, retaining unknown fields. Version 1 enums are closed. Changed meaning/input requires a new wire version and fixed methods. Canonical `JSON.stringify` UTF-8 bounds are checked before schema decoding (parsed transport JSON, not raw HTTP/preparse allocation): input 16KiB, describe 2KiB, each complete presentation stamp `{pluginId:ROW_PLUGIN_ID,schema:ROW_SCHEMA,data}` 4KiB, response 60KiB. Presentation depth remains below context-recognition's depth-eight limit. Oversized stamps become unavailable individually without removing portraits. If the complete batch exceeds 60KiB, ready rows become unavailable in reverse occurrence order until it fits. A malformed row becomes unavailable; no malformed ready stamp reaches the host.
+
+Supplier deadline 3500ms; caller deadline 4500ms, below hosted owner's 5000ms. Supplier registration admits at most two in-flight source reads, no queue; a noncooperative source continues occupying its slot after timeout. One client admits one read at a time; cancelled/nonsettling calls do not open additional remote work. Caller abort fences local delivery, not proof of remote cancellation. Source adapters must respect signals between bounded stages. ID reads deduplicate <=16 IDs; source repeats explicit parent and lifecycle-owner root checks, hidden/deleted/archive checks. Unknown lineage is unavailable. No full owner/lifecycle tables or family traversal. Sender history <=25 events/ID, concurrency <=2; profile keys are batched, <=200 per call. Supplier-specific total profile and table bounds belong in its conformance evidence.
+
+Inbox registers `inbox-sidebar-nerd/thread-row@1` lazily in its content-script context, with `methods:[inboxRowsV1Read]`. `assertRowPresentation` rejects missing/mismatched read allowlists even on permissive hosts. Host creates one owner-bound presentation client from that exact negotiated entry, validates the response, then renders each data stamp/revision through context-recognition 0.5.2. The actual shared body is inert: no per-row proxy, root Inbox, controls, observers or timers. Host owns role=option, stable accessible name and usable fallback. Registration disappearance or renderer/source failure must preserve those host responsibilities.
+
+Root and /bb contain no SDK runtime imports; /bb injects registration and transport. /testing uses the public SDK fake host and invokes the real registered methods. The /testing entry uses the SDK testing entry and its documented optional testing peers (better-sqlite3, cron-parser, hono). Inject createHost to reuse an installed SDK fake host and its SQLite adaptation; the default uses the package-resolved SDK. Package tests and supplier conformance establish source behavior only. Actual browser/body parity, packaged leaf resolution, reload and CSS proof remain adopter obligations.

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,5 @@
-# Temporary Holding Version
+# @phosphorco/bb-inbox-rows
 
-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.
+A small published contract for bounded Inbox row hydration. It ships schemas and byte checks (root), injected public-SDK/identity registration and caller transport (`/bb`), and real-handler conformance (`/testing`). No React or source storage.
+
+Read [CONTRACT.md](CONTRACT.md) for ownership, wire shapes and work limits. Hosts discover via the listed plugin API and `inboxRowsV1Describe`, then create one batch client; each occurrence keeps a native-navigable fallback. Inbox owns the separately registered lazy presentation and genuine shared native body.

package/dist/bb.js

@@ -0,0 +1,222 @@
+// src/bb.ts
+import { z as z2 } from "zod";
+
+// src/index.ts
+import { z } from "zod";
+var PROTOCOL = "phosphor.bb-inbox-rows";
+var METHODS = Object.freeze({ describe: "inboxRowsV1Describe", read: "inboxRowsV1Read" });
+var ROW_PLUGIN_ID = "inbox-sidebar-nerd";
+var ROW_SCHEMA = "inbox-sidebar-nerd/thread-row@1";
+var LIMITS = Object.freeze({ occurrences: 16, stampBytes: 4096, responseBytes: 60 * 1024, inputBytes: 16 * 1024, describeBytes: 2048, supplierMs: 3500, callMs: 4500, senderEvents: 25, senderConcurrency: 2, profileKeys: 200 });
+var token = z.string().min(1).max(256);
+var key = z.string().min(1).max(512);
+var text = z.string().max(1024);
+var count = z.number().int().min(0).max(1e6);
+var time = z.number().finite().nonnegative();
+var faceSchema = z.object({ key, name: text.nullable(), imageUrl: z.string().max(2048).nullable(), label: text, external: z.boolean() }).passthrough();
+var rowDataSchema = z.object({
+  v: z.literal(1),
+  threadId: token,
+  title: text,
+  groupPath: text.nullable(),
+  tags: z.array(z.string().max(256)).max(3),
+  tagOverflow: count,
+  owners: z.array(faceSchema).max(2),
+  ownerOverflow: count,
+  ownerOverflowLabel: text,
+  participants: z.array(faceSchema).max(2),
+  participantOverflow: count,
+  senderDescription: text,
+  status: z.object({ tone: z.enum(["done", "snoozed", "waiting-for-reset", "failed", "needs-you", "working", "woke", "ready", "quiet"]), label: text }).passthrough(),
+  time: z.object({ at: time, text: z.string().max(128), title: z.string().max(256) }).passthrough()
+}).passthrough();
+var readInputSchema = z.object({ version: z.literal(1), occurrences: z.array(z.object({ key: token, threadId: token }).strict()).min(1).max(LIMITS.occurrences), archiveMode: z.enum(["active", "include-archived"]), viewAs: key.nullable().optional() }).strict().superRefine((v, ctx) => {
+  if (new Set(v.occurrences.map((r) => r.key)).size !== v.occurrences.length)
+    ctx.addIssue({ code: "custom", message: "Duplicate occurrence key" });
+});
+var unavailableReasonSchema = z.enum(["not-found", "not-top-level", "excluded", "timeout", "source-error", "oversize"]);
+var ready = z.object({ key: token, threadId: token, state: z.literal("ready"), revision: token, data: rowDataSchema }).passthrough();
+var unavailable = z.object({ key: token, threadId: token, state: z.literal("unavailable"), reason: unavailableReasonSchema }).passthrough();
+var readOutputSchema = z.object({ version: z.literal(1), ownerKey: key.nullable(), revision: token, rows: z.array(z.discriminatedUnion("state", [ready, unavailable])).min(1).max(LIMITS.occurrences) }).passthrough();
+var describeEnvelopeSchema = z.object({ protocol: z.literal(PROTOCOL), versions: z.array(z.number().int().positive()).max(16) }).passthrough();
+var describeSchema = describeEnvelopeSchema.extend({ schema: z.literal(ROW_SCHEMA), readMethod: z.literal(METHODS.read), limits: z.object({ occurrences: z.literal(16), stampBytes: z.literal(4096), responseBytes: z.literal(61440), supplierMs: z.literal(3500) }).passthrough() });
+var DESCRIPTION = { protocol: PROTOCOL, versions: [1], schema: ROW_SCHEMA, readMethod: METHODS.read, limits: { occurrences: 16, stampBytes: 4096, responseBytes: 61440, supplierMs: 3500 } };
+function canonicalBytes(value) {
+  const json = JSON.stringify(value);
+  if (json === undefined)
+    throw Error("Expected JSON");
+  return new TextEncoder().encode(json).byteLength;
+}
+function parseBounded(schema, raw, max) {
+  if (canonicalBytes(raw) > max)
+    throw RangeError("Inbox rows byte limit");
+  return schema.parse(raw);
+}
+function parseReadInput(raw) {
+  return parseBounded(readInputSchema, raw, LIMITS.inputBytes);
+}
+function rowPresentation(raw) {
+  return { pluginId: ROW_PLUGIN_ID, schema: ROW_SCHEMA, data: raw };
+}
+function parseRowData(raw) {
+  if (canonicalBytes({ pluginId: ROW_PLUGIN_ID, schema: ROW_SCHEMA, data: raw }) > LIMITS.stampBytes)
+    throw RangeError("Inbox stamp byte limit");
+  const visit = (value, depth) => {
+    if (depth > 8)
+      throw RangeError("Inbox stamp depth limit");
+    if (value && typeof value === "object")
+      for (const child of Object.values(value))
+        visit(child, depth + 1);
+  };
+  visit(raw, 0);
+  return rowDataSchema.parse(raw);
+}
+function validateReadOutput(input, output) {
+  if (input.viewAs != null && output.ownerKey !== input.viewAs)
+    throw Error("Inbox row owner lens mismatch");
+  if (output.rows.length !== input.occurrences.length)
+    throw Error("Missing Inbox row occurrence");
+  const requested = new Map(input.occurrences.map((o) => [o.key, o.threadId])), seen = new Set;
+  for (const row of output.rows) {
+    if (seen.has(row.key) || requested.get(row.key) !== row.threadId)
+      throw Error("Unexpected Inbox row occurrence");
+    seen.add(row.key);
+    if (row.state === "ready") {
+      if (row.data.threadId !== row.threadId)
+        throw Error("Inbox row data identity mismatch");
+      parseRowData(row.data);
+    }
+  }
+  return output;
+}
+function parseReadOutput(input, raw) {
+  return validateReadOutput(input, parseBounded(readOutputSchema, raw, LIMITS.responseBytes));
+}
+function boundReadOutput(input, raw) {
+  const rows = raw.rows.map((row) => {
+    if (row.state === "unavailable")
+      return row;
+    try {
+      parseRowData(row.data);
+      return row;
+    } catch {
+      let oversized = false;
+      try {
+        oversized = canonicalBytes(rowPresentation(row.data)) > LIMITS.stampBytes;
+      } catch {}
+      return { key: row.key, threadId: row.threadId, state: "unavailable", reason: oversized ? "oversize" : "source-error" };
+    }
+  });
+  const output = { ...raw, rows };
+  for (let index = rows.length - 1;canonicalBytes(output) > LIMITS.responseBytes && index >= 0; index--) {
+    const row = rows[index];
+    if (row.state === "ready")
+      rows[index] = { key: row.key, threadId: row.threadId, state: "unavailable", reason: "oversize" };
+  }
+  return parseReadOutput(input, output);
+}
+
+// src/bb.ts
+function sdkSchema(schema) {
+  return { "~standard": { version: 1, vendor: "bb-inbox-rows", jsonSchema: { input: () => schema.toJSONSchema({ io: "input", unrepresentable: "any" }), output: () => schema.toJSONSchema({ io: "output", unrepresentable: "any" }) }, validate(value) {
+    const r = schema.safeParse(value);
+    return r.success ? { value: r.data } : { issues: r.error.issues };
+  } } };
+}
+var inboxRowsRpcContract = {
+  [METHODS.describe]: { input: sdkSchema(z2.null()), output: sdkSchema(z2.unknown()) },
+  [METHODS.read]: { input: sdkSchema(readInputSchema), output: sdkSchema(z2.unknown()) }
+};
+function createInboxRowsHandlers(supplier) {
+  let pending = 0;
+  return {
+    describe(raw = null) {
+      z2.null().parse(raw);
+      return DESCRIPTION;
+    },
+    async read(raw, context) {
+      const input = parseReadInput(raw);
+      const failed = (reason) => ({ version: 1, ownerKey: input.viewAs ?? null, revision: "unavailable", rows: input.occurrences.map((o) => ({ ...o, state: "unavailable", reason })) });
+      if (pending >= 2)
+        return failed("source-error");
+      const controller = new AbortController;
+      let timer;
+      pending++;
+      const flight = Promise.resolve().then(() => supplier.read(input, context, controller.signal)).finally(() => {
+        pending--;
+      });
+      const deadline = new Promise((resolve) => {
+        timer = setTimeout(() => {
+          controller.abort();
+          resolve(failed("timeout"));
+        }, LIMITS.supplierMs);
+      });
+      try {
+        return boundReadOutput(input, await Promise.race([flight, deadline]));
+      } catch {
+        return failed(controller.signal.aborted ? "timeout" : "source-error");
+      } finally {
+        clearTimeout(timer);
+        controller.abort();
+      }
+    }
+  };
+}
+function registerInboxRowsSupplier(register, supplier) {
+  const h = createInboxRowsHandlers(supplier);
+  return register(inboxRowsRpcContract, { [METHODS.describe]: (input) => h.describe(input), [METHODS.read]: (input, context) => h.read(input, context) });
+}
+function createInboxRowsClient(transport, pluginId) {
+  let pending = false;
+  async function call(method, input, outer) {
+    if (pending)
+      throw Error("Inbox row request still outstanding");
+    outer?.throwIfAborted();
+    pending = true;
+    const controller = new AbortController, signal = outer ? AbortSignal.any([outer, controller.signal]) : controller.signal;
+    let timer, abort;
+    const flight = Promise.resolve().then(() => {
+      signal.throwIfAborted();
+      return transport({ pluginId, method, input, signal });
+    }).finally(() => {
+      pending = false;
+    });
+    const deadline = new Promise((_, reject) => {
+      timer = setTimeout(() => {
+        reject(Error("Inbox row read timed out"));
+        controller.abort();
+      }, LIMITS.callMs);
+    });
+    const aborted = new Promise((_, reject) => {
+      abort = () => reject(new DOMException("Aborted", "AbortError"));
+      signal.addEventListener("abort", abort, { once: true });
+    });
+    try {
+      return await Promise.race([flight, deadline, aborted]);
+    } finally {
+      clearTimeout(timer);
+      if (abort)
+        signal.removeEventListener("abort", abort);
+      controller.abort();
+    }
+  }
+  return {
+    pluginId,
+    async describe(signal) {
+      const raw = await call(METHODS.describe, null, signal), envelope = parseBounded(describeEnvelopeSchema, raw, LIMITS.describeBytes);
+      if (!envelope.versions.includes(1))
+        throw Error("Unsupported Inbox rows version");
+      return parseBounded(describeSchema, raw, LIMITS.describeBytes);
+    },
+    async read(raw, signal) {
+      const input = parseReadInput(raw);
+      return parseReadOutput(input, await call(METHODS.read, input, signal));
+    }
+  };
+}
+export {
+  registerInboxRowsSupplier,
+  inboxRowsRpcContract,
+  createInboxRowsHandlers,
+  createInboxRowsClient
+};

package/dist/index.js

@@ -0,0 +1,141 @@
+// src/index.ts
+import { z } from "zod";
+var PROTOCOL = "phosphor.bb-inbox-rows";
+var METHODS = Object.freeze({ describe: "inboxRowsV1Describe", read: "inboxRowsV1Read" });
+var ROW_PLUGIN_ID = "inbox-sidebar-nerd";
+var ROW_SCHEMA = "inbox-sidebar-nerd/thread-row@1";
+var LIMITS = Object.freeze({ occurrences: 16, stampBytes: 4096, responseBytes: 60 * 1024, inputBytes: 16 * 1024, describeBytes: 2048, supplierMs: 3500, callMs: 4500, senderEvents: 25, senderConcurrency: 2, profileKeys: 200 });
+var token = z.string().min(1).max(256);
+var key = z.string().min(1).max(512);
+var text = z.string().max(1024);
+var count = z.number().int().min(0).max(1e6);
+var time = z.number().finite().nonnegative();
+var faceSchema = z.object({ key, name: text.nullable(), imageUrl: z.string().max(2048).nullable(), label: text, external: z.boolean() }).passthrough();
+var rowDataSchema = z.object({
+  v: z.literal(1),
+  threadId: token,
+  title: text,
+  groupPath: text.nullable(),
+  tags: z.array(z.string().max(256)).max(3),
+  tagOverflow: count,
+  owners: z.array(faceSchema).max(2),
+  ownerOverflow: count,
+  ownerOverflowLabel: text,
+  participants: z.array(faceSchema).max(2),
+  participantOverflow: count,
+  senderDescription: text,
+  status: z.object({ tone: z.enum(["done", "snoozed", "waiting-for-reset", "failed", "needs-you", "working", "woke", "ready", "quiet"]), label: text }).passthrough(),
+  time: z.object({ at: time, text: z.string().max(128), title: z.string().max(256) }).passthrough()
+}).passthrough();
+var readInputSchema = z.object({ version: z.literal(1), occurrences: z.array(z.object({ key: token, threadId: token }).strict()).min(1).max(LIMITS.occurrences), archiveMode: z.enum(["active", "include-archived"]), viewAs: key.nullable().optional() }).strict().superRefine((v, ctx) => {
+  if (new Set(v.occurrences.map((r) => r.key)).size !== v.occurrences.length)
+    ctx.addIssue({ code: "custom", message: "Duplicate occurrence key" });
+});
+var unavailableReasonSchema = z.enum(["not-found", "not-top-level", "excluded", "timeout", "source-error", "oversize"]);
+var ready = z.object({ key: token, threadId: token, state: z.literal("ready"), revision: token, data: rowDataSchema }).passthrough();
+var unavailable = z.object({ key: token, threadId: token, state: z.literal("unavailable"), reason: unavailableReasonSchema }).passthrough();
+var readOutputSchema = z.object({ version: z.literal(1), ownerKey: key.nullable(), revision: token, rows: z.array(z.discriminatedUnion("state", [ready, unavailable])).min(1).max(LIMITS.occurrences) }).passthrough();
+var describeEnvelopeSchema = z.object({ protocol: z.literal(PROTOCOL), versions: z.array(z.number().int().positive()).max(16) }).passthrough();
+var describeSchema = describeEnvelopeSchema.extend({ schema: z.literal(ROW_SCHEMA), readMethod: z.literal(METHODS.read), limits: z.object({ occurrences: z.literal(16), stampBytes: z.literal(4096), responseBytes: z.literal(61440), supplierMs: z.literal(3500) }).passthrough() });
+var DESCRIPTION = { protocol: PROTOCOL, versions: [1], schema: ROW_SCHEMA, readMethod: METHODS.read, limits: { occurrences: 16, stampBytes: 4096, responseBytes: 61440, supplierMs: 3500 } };
+function canonicalBytes(value) {
+  const json = JSON.stringify(value);
+  if (json === undefined)
+    throw Error("Expected JSON");
+  return new TextEncoder().encode(json).byteLength;
+}
+function parseBounded(schema, raw, max) {
+  if (canonicalBytes(raw) > max)
+    throw RangeError("Inbox rows byte limit");
+  return schema.parse(raw);
+}
+function parseReadInput(raw) {
+  return parseBounded(readInputSchema, raw, LIMITS.inputBytes);
+}
+function rowPresentation(raw) {
+  return { pluginId: ROW_PLUGIN_ID, schema: ROW_SCHEMA, data: raw };
+}
+function parseRowData(raw) {
+  if (canonicalBytes({ pluginId: ROW_PLUGIN_ID, schema: ROW_SCHEMA, data: raw }) > LIMITS.stampBytes)
+    throw RangeError("Inbox stamp byte limit");
+  const visit = (value, depth) => {
+    if (depth > 8)
+      throw RangeError("Inbox stamp depth limit");
+    if (value && typeof value === "object")
+      for (const child of Object.values(value))
+        visit(child, depth + 1);
+  };
+  visit(raw, 0);
+  return rowDataSchema.parse(raw);
+}
+function validateReadOutput(input, output) {
+  if (input.viewAs != null && output.ownerKey !== input.viewAs)
+    throw Error("Inbox row owner lens mismatch");
+  if (output.rows.length !== input.occurrences.length)
+    throw Error("Missing Inbox row occurrence");
+  const requested = new Map(input.occurrences.map((o) => [o.key, o.threadId])), seen = new Set;
+  for (const row of output.rows) {
+    if (seen.has(row.key) || requested.get(row.key) !== row.threadId)
+      throw Error("Unexpected Inbox row occurrence");
+    seen.add(row.key);
+    if (row.state === "ready") {
+      if (row.data.threadId !== row.threadId)
+        throw Error("Inbox row data identity mismatch");
+      parseRowData(row.data);
+    }
+  }
+  return output;
+}
+function parseReadOutput(input, raw) {
+  return validateReadOutput(input, parseBounded(readOutputSchema, raw, LIMITS.responseBytes));
+}
+function boundReadOutput(input, raw) {
+  const rows = raw.rows.map((row) => {
+    if (row.state === "unavailable")
+      return row;
+    try {
+      parseRowData(row.data);
+      return row;
+    } catch {
+      let oversized = false;
+      try {
+        oversized = canonicalBytes(rowPresentation(row.data)) > LIMITS.stampBytes;
+      } catch {}
+      return { key: row.key, threadId: row.threadId, state: "unavailable", reason: oversized ? "oversize" : "source-error" };
+    }
+  });
+  const output = { ...raw, rows };
+  for (let index = rows.length - 1;canonicalBytes(output) > LIMITS.responseBytes && index >= 0; index--) {
+    const row = rows[index];
+    if (row.state === "ready")
+      rows[index] = { key: row.key, threadId: row.threadId, state: "unavailable", reason: "oversize" };
+  }
+  return parseReadOutput(input, output);
+}
+function assertRowPresentation(entry) {
+  if (entry.schema !== ROW_SCHEMA || !entry.methods.includes(METHODS.read))
+    throw Error("Inbox row registration must allow the fixed batch read method");
+}
+export {
+  validateReadOutput,
+  unavailableReasonSchema,
+  rowPresentation,
+  rowDataSchema,
+  readOutputSchema,
+  readInputSchema,
+  parseRowData,
+  parseReadOutput,
+  parseReadInput,
+  parseBounded,
+  describeSchema,
+  describeEnvelopeSchema,
+  canonicalBytes,
+  boundReadOutput,
+  assertRowPresentation,
+  ROW_SCHEMA,
+  ROW_PLUGIN_ID,
+  PROTOCOL,
+  METHODS,
+  LIMITS,
+  DESCRIPTION
+};

package/dist/testing.js

@@ -0,0 +1,203 @@
+// src/testing.ts
+import { createFakePluginHost } from "@get-bb/plugin-sdk/testing";
+
+// src/bb.ts
+import { z as z2 } from "zod";
+
+// src/index.ts
+import { z } from "zod";
+var PROTOCOL = "phosphor.bb-inbox-rows";
+var METHODS = Object.freeze({ describe: "inboxRowsV1Describe", read: "inboxRowsV1Read" });
+var ROW_PLUGIN_ID = "inbox-sidebar-nerd";
+var ROW_SCHEMA = "inbox-sidebar-nerd/thread-row@1";
+var LIMITS = Object.freeze({ occurrences: 16, stampBytes: 4096, responseBytes: 60 * 1024, inputBytes: 16 * 1024, describeBytes: 2048, supplierMs: 3500, callMs: 4500, senderEvents: 25, senderConcurrency: 2, profileKeys: 200 });
+var token = z.string().min(1).max(256);
+var key = z.string().min(1).max(512);
+var text = z.string().max(1024);
+var count = z.number().int().min(0).max(1e6);
+var time = z.number().finite().nonnegative();
+var faceSchema = z.object({ key, name: text.nullable(), imageUrl: z.string().max(2048).nullable(), label: text, external: z.boolean() }).passthrough();
+var rowDataSchema = z.object({
+  v: z.literal(1),
+  threadId: token,
+  title: text,
+  groupPath: text.nullable(),
+  tags: z.array(z.string().max(256)).max(3),
+  tagOverflow: count,
+  owners: z.array(faceSchema).max(2),
+  ownerOverflow: count,
+  ownerOverflowLabel: text,
+  participants: z.array(faceSchema).max(2),
+  participantOverflow: count,
+  senderDescription: text,
+  status: z.object({ tone: z.enum(["done", "snoozed", "waiting-for-reset", "failed", "needs-you", "working", "woke", "ready", "quiet"]), label: text }).passthrough(),
+  time: z.object({ at: time, text: z.string().max(128), title: z.string().max(256) }).passthrough()
+}).passthrough();
+var readInputSchema = z.object({ version: z.literal(1), occurrences: z.array(z.object({ key: token, threadId: token }).strict()).min(1).max(LIMITS.occurrences), archiveMode: z.enum(["active", "include-archived"]), viewAs: key.nullable().optional() }).strict().superRefine((v, ctx) => {
+  if (new Set(v.occurrences.map((r) => r.key)).size !== v.occurrences.length)
+    ctx.addIssue({ code: "custom", message: "Duplicate occurrence key" });
+});
+var unavailableReasonSchema = z.enum(["not-found", "not-top-level", "excluded", "timeout", "source-error", "oversize"]);
+var ready = z.object({ key: token, threadId: token, state: z.literal("ready"), revision: token, data: rowDataSchema }).passthrough();
+var unavailable = z.object({ key: token, threadId: token, state: z.literal("unavailable"), reason: unavailableReasonSchema }).passthrough();
+var readOutputSchema = z.object({ version: z.literal(1), ownerKey: key.nullable(), revision: token, rows: z.array(z.discriminatedUnion("state", [ready, unavailable])).min(1).max(LIMITS.occurrences) }).passthrough();
+var describeEnvelopeSchema = z.object({ protocol: z.literal(PROTOCOL), versions: z.array(z.number().int().positive()).max(16) }).passthrough();
+var describeSchema = describeEnvelopeSchema.extend({ schema: z.literal(ROW_SCHEMA), readMethod: z.literal(METHODS.read), limits: z.object({ occurrences: z.literal(16), stampBytes: z.literal(4096), responseBytes: z.literal(61440), supplierMs: z.literal(3500) }).passthrough() });
+var DESCRIPTION = { protocol: PROTOCOL, versions: [1], schema: ROW_SCHEMA, readMethod: METHODS.read, limits: { occurrences: 16, stampBytes: 4096, responseBytes: 61440, supplierMs: 3500 } };
+function canonicalBytes(value) {
+  const json = JSON.stringify(value);
+  if (json === undefined)
+    throw Error("Expected JSON");
+  return new TextEncoder().encode(json).byteLength;
+}
+function parseBounded(schema, raw, max) {
+  if (canonicalBytes(raw) > max)
+    throw RangeError("Inbox rows byte limit");
+  return schema.parse(raw);
+}
+function parseReadInput(raw) {
+  return parseBounded(readInputSchema, raw, LIMITS.inputBytes);
+}
+function parseRowData(raw) {
+  if (canonicalBytes({ pluginId: ROW_PLUGIN_ID, schema: ROW_SCHEMA, data: raw }) > LIMITS.stampBytes)
+    throw RangeError("Inbox stamp byte limit");
+  const visit = (value, depth) => {
+    if (depth > 8)
+      throw RangeError("Inbox stamp depth limit");
+    if (value && typeof value === "object")
+      for (const child of Object.values(value))
+        visit(child, depth + 1);
+  };
+  visit(raw, 0);
+  return rowDataSchema.parse(raw);
+}
+function validateReadOutput(input, output) {
+  if (input.viewAs != null && output.ownerKey !== input.viewAs)
+    throw Error("Inbox row owner lens mismatch");
+  if (output.rows.length !== input.occurrences.length)
+    throw Error("Missing Inbox row occurrence");
+  const requested = new Map(input.occurrences.map((o) => [o.key, o.threadId])), seen = new Set;
+  for (const row of output.rows) {
+    if (seen.has(row.key) || requested.get(row.key) !== row.threadId)
+      throw Error("Unexpected Inbox row occurrence");
+    seen.add(row.key);
+    if (row.state === "ready") {
+      if (row.data.threadId !== row.threadId)
+        throw Error("Inbox row data identity mismatch");
+      parseRowData(row.data);
+    }
+  }
+  return output;
+}
+function parseReadOutput(input, raw) {
+  return validateReadOutput(input, parseBounded(readOutputSchema, raw, LIMITS.responseBytes));
+}
+function assertRowPresentation(entry) {
+  if (entry.schema !== ROW_SCHEMA || !entry.methods.includes(METHODS.read))
+    throw Error("Inbox row registration must allow the fixed batch read method");
+}
+
+// src/bb.ts
+function sdkSchema(schema) {
+  return { "~standard": { version: 1, vendor: "bb-inbox-rows", jsonSchema: { input: () => schema.toJSONSchema({ io: "input", unrepresentable: "any" }), output: () => schema.toJSONSchema({ io: "output", unrepresentable: "any" }) }, validate(value) {
+    const r = schema.safeParse(value);
+    return r.success ? { value: r.data } : { issues: r.error.issues };
+  } } };
+}
+var inboxRowsRpcContract = {
+  [METHODS.describe]: { input: sdkSchema(z2.null()), output: sdkSchema(z2.unknown()) },
+  [METHODS.read]: { input: sdkSchema(readInputSchema), output: sdkSchema(z2.unknown()) }
+};
+function createInboxRowsClient(transport, pluginId) {
+  let pending = false;
+  async function call(method, input, outer) {
+    if (pending)
+      throw Error("Inbox row request still outstanding");
+    outer?.throwIfAborted();
+    pending = true;
+    const controller = new AbortController, signal = outer ? AbortSignal.any([outer, controller.signal]) : controller.signal;
+    let timer, abort;
+    const flight = Promise.resolve().then(() => {
+      signal.throwIfAborted();
+      return transport({ pluginId, method, input, signal });
+    }).finally(() => {
+      pending = false;
+    });
+    const deadline = new Promise((_, reject) => {
+      timer = setTimeout(() => {
+        reject(Error("Inbox row read timed out"));
+        controller.abort();
+      }, LIMITS.callMs);
+    });
+    const aborted = new Promise((_, reject) => {
+      abort = () => reject(new DOMException("Aborted", "AbortError"));
+      signal.addEventListener("abort", abort, { once: true });
+    });
+    try {
+      return await Promise.race([flight, deadline, aborted]);
+    } finally {
+      clearTimeout(timer);
+      if (abort)
+        signal.removeEventListener("abort", abort);
+      controller.abort();
+    }
+  }
+  return {
+    pluginId,
+    async describe(signal) {
+      const raw = await call(METHODS.describe, null, signal), envelope = parseBounded(describeEnvelopeSchema, raw, LIMITS.describeBytes);
+      if (!envelope.versions.includes(1))
+        throw Error("Unsupported Inbox rows version");
+      return parseBounded(describeSchema, raw, LIMITS.describeBytes);
+    },
+    async read(raw, signal) {
+      const input = parseReadInput(raw);
+      return parseReadOutput(input, await call(METHODS.read, input, signal));
+    }
+  };
+}
+
+// src/testing.ts
+async function runInboxRowsSupplierConformance(options) {
+  const host = (options.createHost ?? createFakePluginHost)({ pluginId: options.pluginId }), checks = [];
+  const check = async (name, fn) => {
+    try {
+      await fn();
+      checks.push({ name, passed: true });
+    } catch (e) {
+      checks.push({ name, passed: false, error: String(e) });
+    }
+  };
+  try {
+    await check("real-registration", () => options.register(host.bb));
+    const client = createInboxRowsClient(async (c) => {
+      if (c.pluginId !== options.pluginId)
+        throw Error("Wrong owner");
+      return host.harness.behavior.callRpc(c.method, c.input);
+    }, options.pluginId);
+    await check("version-negotiation", () => client.describe());
+    await check("presentation-read-allowlist", () => assertRowPresentation(options.presentation));
+    await check("strict-input", async () => {
+      for (const input of [{ version: 1, occurrences: [{ key: "k", threadId: "t" }], archiveMode: "active", extra: true }, { version: 1, occurrences: [{ key: "k", threadId: "t", extra: true }], archiveMode: "active" }, { version: 1, occurrences: [{ key: "k", threadId: "t" }, { key: "k", threadId: "t2" }], archiveMode: "active" }]) {
+        let rejected = false;
+        try {
+          await host.harness.behavior.callRpc(METHODS.read, input);
+        } catch (e) {
+          rejected = e.name === "ZodError" || e.code === "invalid_input";
+        }
+        if (!rejected)
+          throw Error("Malformed input was not rejected with validation evidence");
+      }
+    });
+    for (const [i, c] of options.cases.entries())
+      await check(`read:${i}`, async () => c.check(await client.read(c.input)));
+    if (!options.cases.length)
+      checks.push({ name: "supplier-owned-witnesses", passed: false });
+    return { pluginId: options.pluginId, proof: "source-conformance", passed: checks.every((c) => c.passed), checks };
+  } finally {
+    await host.harness.lifecycle.dispose();
+  }
+}
+export {
+  runInboxRowsSupplierConformance
+};

package/dist/types/bb.d.ts

@@ -0,0 +1,134 @@
+import type { StandardSchemaV1 } from '@get-bb/plugin-sdk';
+import { METHODS, type ReadInput, type ReadOutput } from './index.js';
+export declare const inboxRowsRpcContract: {
+    inboxRowsV1Describe: {
+        input: StandardSchemaV1<null, null>;
+        output: StandardSchemaV1<unknown, unknown>;
+    };
+    inboxRowsV1Read: {
+        input: StandardSchemaV1<{
+            version: 1;
+            occurrences: {
+                key: string;
+                threadId: string;
+            }[];
+            archiveMode: "active" | "include-archived";
+            viewAs?: string | null | undefined;
+        }, {
+            version: 1;
+            occurrences: {
+                key: string;
+                threadId: string;
+            }[];
+            archiveMode: "active" | "include-archived";
+            viewAs?: string | null | undefined;
+        }>;
+        output: StandardSchemaV1<unknown, unknown>;
+    };
+};
+export interface InboxRowsSupplier<Context = void> {
+    read(input: ReadInput, context: Context | undefined, signal: AbortSignal): Promise<ReadOutput>;
+}
+export declare function createInboxRowsHandlers<Context>(supplier: InboxRowsSupplier<Context>): {
+    describe(raw?: unknown): {
+        readonly protocol: "phosphor.bb-inbox-rows";
+        readonly versions: readonly [1];
+        readonly schema: "inbox-sidebar-nerd/thread-row@1";
+        readonly readMethod: "inboxRowsV1Read";
+        readonly limits: {
+            readonly occurrences: 16;
+            readonly stampBytes: 4096;
+            readonly responseBytes: 61440;
+            readonly supplierMs: 3500;
+        };
+    };
+    read(raw: unknown, context?: Context): Promise<ReadOutput>;
+};
+/** Inject the public SDK registrar, or an identity binding's registrar preserving invocation. */
+export declare function registerInboxRowsSupplier<Context, Result>(register: (contract: typeof inboxRowsRpcContract, handlers: {
+    [METHODS.describe]: (input: unknown) => unknown;
+    [METHODS.read]: (input: unknown, context?: Context) => Promise<ReadOutput>;
+}) => Result, supplier: InboxRowsSupplier<Context>): Result;
+export type InboxRowsTransport = (call: {
+    pluginId: string;
+    method: string;
+    input: unknown;
+    signal: AbortSignal;
+}) => Promise<unknown>;
+/** One shared caller resource. Selection changes must not invoke this client. */
+export declare function createInboxRowsClient(transport: InboxRowsTransport, pluginId: string): {
+    pluginId: string;
+    describe(signal?: AbortSignal): Promise<{
+        [x: string]: unknown;
+        protocol: "phosphor.bb-inbox-rows";
+        versions: number[];
+        schema: "inbox-sidebar-nerd/thread-row@1";
+        readMethod: "inboxRowsV1Read";
+        limits: {
+            [x: string]: unknown;
+            occurrences: 16;
+            stampBytes: 4096;
+            responseBytes: 61440;
+            supplierMs: 3500;
+        };
+    }>;
+    read(raw: ReadInput, signal?: AbortSignal): Promise<{
+        [x: string]: unknown;
+        version: 1;
+        ownerKey: string | null;
+        revision: string;
+        rows: ({
+            [x: string]: unknown;
+            key: string;
+            threadId: string;
+            state: "ready";
+            revision: string;
+            data: {
+                [x: string]: unknown;
+                v: 1;
+                threadId: string;
+                title: string;
+                groupPath: string | null;
+                tags: string[];
+                tagOverflow: number;
+                owners: {
+                    [x: string]: unknown;
+                    key: string;
+                    name: string | null;
+                    imageUrl: string | null;
+                    label: string;
+                    external: boolean;
+                }[];
+                ownerOverflow: number;
+                ownerOverflowLabel: string;
+                participants: {
+                    [x: string]: unknown;
+                    key: string;
+                    name: string | null;
+                    imageUrl: string | null;
+                    label: string;
+                    external: boolean;
+                }[];
+                participantOverflow: number;
+                senderDescription: string;
+                status: {
+                    [x: string]: unknown;
+                    tone: "done" | "snoozed" | "waiting-for-reset" | "failed" | "needs-you" | "working" | "woke" | "ready" | "quiet";
+                    label: string;
+                };
+                time: {
+                    [x: string]: unknown;
+                    at: number;
+                    text: string;
+                    title: string;
+                };
+            };
+        } | {
+            [x: string]: unknown;
+            key: string;
+            threadId: string;
+            state: "unavailable";
+            reason: "not-found" | "not-top-level" | "excluded" | "timeout" | "source-error" | "oversize";
+        })[];
+    }>;
+};

package/dist/types/index.d.ts

@@ -0,0 +1,244 @@
+import { z } from 'zod';
+export declare const PROTOCOL = "phosphor.bb-inbox-rows";
+export declare const METHODS: Readonly<{
+    describe: "inboxRowsV1Describe";
+    read: "inboxRowsV1Read";
+}>;
+export declare const ROW_PLUGIN_ID = "inbox-sidebar-nerd";
+export declare const ROW_SCHEMA = "inbox-sidebar-nerd/thread-row@1";
+export declare const LIMITS: Readonly<{
+    occurrences: 16;
+    stampBytes: 4096;
+    responseBytes: number;
+    inputBytes: number;
+    describeBytes: 2048;
+    supplierMs: 3500;
+    callMs: 4500;
+    senderEvents: 25;
+    senderConcurrency: 2;
+    profileKeys: 200;
+}>;
+/** Every evolving output object preserves additive fields; raw bytes are checked before decoding. */
+export declare const rowDataSchema: z.ZodObject<{
+    v: z.ZodLiteral<1>;
+    threadId: z.ZodString;
+    title: z.ZodString;
+    groupPath: z.ZodNullable<z.ZodString>;
+    tags: z.ZodArray<z.ZodString>;
+    tagOverflow: z.ZodNumber;
+    owners: z.ZodArray<z.ZodObject<{
+        key: z.ZodString;
+        name: z.ZodNullable<z.ZodString>;
+        imageUrl: z.ZodNullable<z.ZodString>;
+        label: z.ZodString;
+        external: z.ZodBoolean;
+    }, z.core.$loose>>;
+    ownerOverflow: z.ZodNumber;
+    ownerOverflowLabel: z.ZodString;
+    participants: z.ZodArray<z.ZodObject<{
+        key: z.ZodString;
+        name: z.ZodNullable<z.ZodString>;
+        imageUrl: z.ZodNullable<z.ZodString>;
+        label: z.ZodString;
+        external: z.ZodBoolean;
+    }, z.core.$loose>>;
+    participantOverflow: z.ZodNumber;
+    senderDescription: z.ZodString;
+    status: z.ZodObject<{
+        tone: z.ZodEnum<{
+            done: "done";
+            snoozed: "snoozed";
+            "waiting-for-reset": "waiting-for-reset";
+            failed: "failed";
+            "needs-you": "needs-you";
+            working: "working";
+            woke: "woke";
+            ready: "ready";
+            quiet: "quiet";
+        }>;
+        label: z.ZodString;
+    }, z.core.$loose>;
+    time: z.ZodObject<{
+        at: z.ZodNumber;
+        text: z.ZodString;
+        title: z.ZodString;
+    }, z.core.$loose>;
+}, z.core.$loose>;
+export type RowData = z.infer<typeof rowDataSchema>;
+export declare const readInputSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    occurrences: z.ZodArray<z.ZodObject<{
+        key: z.ZodString;
+        threadId: z.ZodString;
+    }, z.core.$strict>>;
+    archiveMode: z.ZodEnum<{
+        active: "active";
+        "include-archived": "include-archived";
+    }>;
+    viewAs: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strict>;
+export type ReadInput = z.infer<typeof readInputSchema>;
+export declare const unavailableReasonSchema: z.ZodEnum<{
+    "not-found": "not-found";
+    "not-top-level": "not-top-level";
+    excluded: "excluded";
+    timeout: "timeout";
+    "source-error": "source-error";
+    oversize: "oversize";
+}>;
+export type UnavailableReason = z.infer<typeof unavailableReasonSchema>;
+export declare const readOutputSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    ownerKey: z.ZodNullable<z.ZodString>;
+    revision: z.ZodString;
+    rows: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        key: z.ZodString;
+        threadId: z.ZodString;
+        state: z.ZodLiteral<"ready">;
+        revision: z.ZodString;
+        data: z.ZodObject<{
+            v: z.ZodLiteral<1>;
+            threadId: z.ZodString;
+            title: z.ZodString;
+            groupPath: z.ZodNullable<z.ZodString>;
+            tags: z.ZodArray<z.ZodString>;
+            tagOverflow: z.ZodNumber;
+            owners: z.ZodArray<z.ZodObject<{
+                key: z.ZodString;
+                name: z.ZodNullable<z.ZodString>;
+                imageUrl: z.ZodNullable<z.ZodString>;
+                label: z.ZodString;
+                external: z.ZodBoolean;
+            }, z.core.$loose>>;
+            ownerOverflow: z.ZodNumber;
+            ownerOverflowLabel: z.ZodString;
+            participants: z.ZodArray<z.ZodObject<{
+                key: z.ZodString;
+                name: z.ZodNullable<z.ZodString>;
+                imageUrl: z.ZodNullable<z.ZodString>;
+                label: z.ZodString;
+                external: z.ZodBoolean;
+            }, z.core.$loose>>;
+            participantOverflow: z.ZodNumber;
+            senderDescription: z.ZodString;
+            status: z.ZodObject<{
+                tone: z.ZodEnum<{
+                    done: "done";
+                    snoozed: "snoozed";
+                    "waiting-for-reset": "waiting-for-reset";
+                    failed: "failed";
+                    "needs-you": "needs-you";
+                    working: "working";
+                    woke: "woke";
+                    ready: "ready";
+                    quiet: "quiet";
+                }>;
+                label: z.ZodString;
+            }, z.core.$loose>;
+            time: z.ZodObject<{
+                at: z.ZodNumber;
+                text: z.ZodString;
+                title: z.ZodString;
+            }, z.core.$loose>;
+        }, z.core.$loose>;
+    }, z.core.$loose>, z.ZodObject<{
+        key: z.ZodString;
+        threadId: z.ZodString;
+        state: z.ZodLiteral<"unavailable">;
+        reason: z.ZodEnum<{
+            "not-found": "not-found";
+            "not-top-level": "not-top-level";
+            excluded: "excluded";
+            timeout: "timeout";
+            "source-error": "source-error";
+            oversize: "oversize";
+        }>;
+    }, z.core.$loose>], "state">>;
+}, z.core.$loose>;
+export type ReadOutput = z.infer<typeof readOutputSchema>;
+export declare const describeEnvelopeSchema: z.ZodObject<{
+    protocol: z.ZodLiteral<"phosphor.bb-inbox-rows">;
+    versions: z.ZodArray<z.ZodNumber>;
+}, z.core.$loose>;
+export declare const describeSchema: z.ZodObject<{
+    protocol: z.ZodLiteral<"phosphor.bb-inbox-rows">;
+    versions: z.ZodArray<z.ZodNumber>;
+    schema: z.ZodLiteral<"inbox-sidebar-nerd/thread-row@1">;
+    readMethod: z.ZodLiteral<"inboxRowsV1Read">;
+    limits: z.ZodObject<{
+        occurrences: z.ZodLiteral<16>;
+        stampBytes: z.ZodLiteral<4096>;
+        responseBytes: z.ZodLiteral<61440>;
+        supplierMs: z.ZodLiteral<3500>;
+    }, z.core.$loose>;
+}, z.core.$loose>;
+export declare const DESCRIPTION: {
+    readonly protocol: "phosphor.bb-inbox-rows";
+    readonly versions: readonly [1];
+    readonly schema: "inbox-sidebar-nerd/thread-row@1";
+    readonly readMethod: "inboxRowsV1Read";
+    readonly limits: {
+        readonly occurrences: 16;
+        readonly stampBytes: 4096;
+        readonly responseBytes: 61440;
+        readonly supplierMs: 3500;
+    };
+};
+/** Canonical transport JSON size, including Unicode, escapes and additive fields. Not raw HTTP bytes. */
+export declare function canonicalBytes(value: unknown): number;
+export declare function parseBounded<T>(schema: z.ZodType<T>, raw: unknown, max: number): T;
+export declare function parseReadInput(raw: unknown): ReadInput;
+export declare function rowPresentation(raw: RowData): {
+    pluginId: string;
+    schema: string;
+    data: {
+        [x: string]: unknown;
+        v: 1;
+        threadId: string;
+        title: string;
+        groupPath: string | null;
+        tags: string[];
+        tagOverflow: number;
+        owners: {
+            [x: string]: unknown;
+            key: string;
+            name: string | null;
+            imageUrl: string | null;
+            label: string;
+            external: boolean;
+        }[];
+        ownerOverflow: number;
+        ownerOverflowLabel: string;
+        participants: {
+            [x: string]: unknown;
+            key: string;
+            name: string | null;
+            imageUrl: string | null;
+            label: string;
+            external: boolean;
+        }[];
+        participantOverflow: number;
+        senderDescription: string;
+        status: {
+            [x: string]: unknown;
+            tone: "done" | "snoozed" | "waiting-for-reset" | "failed" | "needs-you" | "working" | "woke" | "ready" | "quiet";
+            label: string;
+        };
+        time: {
+            [x: string]: unknown;
+            at: number;
+            text: string;
+            title: string;
+        };
+    };
+};
+export declare function parseRowData(raw: unknown): RowData;
+export declare function validateReadOutput(input: ReadInput, output: ReadOutput): ReadOutput;
+export declare function parseReadOutput(input: ReadInput, raw: unknown): ReadOutput;
+/** Deterministic occurrence-order admission. A stamp never loses portraits to fit. */
+export declare function boundReadOutput(input: ReadInput, raw: ReadOutput): ReadOutput;
+/** Presentation metadata is data-only; registration still belongs to Inbox's content script. */
+export declare function assertRowPresentation(entry: {
+    schema: string;
+    methods: readonly string[];
+}): void;

package/dist/types/testing.d.ts

@@ -0,0 +1,36 @@
+import type { BbPluginApi } from '@get-bb/plugin-sdk';
+import { createFakePluginHost } from '@get-bb/plugin-sdk/testing';
+import { type ReadInput, type ReadOutput } from './index.js';
+type FakeHost = ReturnType<typeof createFakePluginHost>;
+export interface InboxRowsConformanceHost {
+    bb: Pick<BbPluginApi, 'rpc' | 'storage'>;
+    harness: {
+        behavior: Pick<FakeHost['harness']['behavior'], 'callRpc'>;
+        lifecycle: Pick<FakeHost['harness']['lifecycle'], 'dispose'>;
+    };
+}
+export declare function runInboxRowsSupplierConformance(options: {
+    pluginId: string;
+    createHost?: (options: {
+        pluginId: string;
+    }) => InboxRowsConformanceHost;
+    register: (bb: InboxRowsConformanceHost['bb']) => unknown | Promise<unknown>;
+    cases: readonly {
+        input: ReadInput;
+        check: (output: ReadOutput) => unknown;
+    }[];
+    presentation: {
+        schema: string;
+        methods: readonly string[];
+    };
+}): Promise<{
+    pluginId: string;
+    proof: "source-conformance";
+    passed: boolean;
+    checks: {
+        name: string;
+        passed: boolean;
+        error?: string;
+    }[];
+}>;
+export {};

package/package.json

@@ -1,6 +1,15 @@
 {
-  "name": "@phosphorco/bb-inbox-rows",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "name": "@phosphorco/bb-inbox-rows", "version": "0.1.1", "description": "Bounded inert Inbox row projections between independently installed BB plugins.",
+  "type": "module", "license": "MIT", "author": "Phosphor",
+  "repository": {"type":"git","url":"git+https://github.com/phosphorco/bb-community-plugins.git","directory":"packages/bb-inbox-rows"},
+  "exports": {
+    ".":{"types":"./dist/types/index.d.ts","import":"./dist/index.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"},
+  "dependencies":{"zod":"^4.3.6"},
+  "peerDependencies":{"@get-bb/plugin-sdk":"^0.6.31"}, "peerDependenciesMeta":{"@get-bb/plugin-sdk":{"optional":true}},
+  "devDependencies":{"@get-bb/plugin-sdk":"0.6.52","@types/node":"^22","bun":"1.3.14","typescript":"^5.9.3"},
+  "scripts":{"build":"bun tools/build.mjs && tsc --project tsconfig.declarations.json","test":"npm run build && node --test test/*.test.mjs","typecheck":"tsc --noEmit"}
+}