@phosphorco/bb-cross-references 0.1.1 → 0.3.0

package/dist/react.js

@@ -365,7 +365,279 @@ function referenceLabelError(value) {
 }
 
 // src/index.ts
+import { z as z3 } from "zod";
+
+// src/recognition.ts
 import { z } from "zod";
+import { canonicalJson, SourceIdentitySchema, SafeHrefSchema } from "@phosphorco/bb-context-recognition";
+var RECOGNITION_CODEC_VERSION = 1;
+var MAX_RECOGNITION_IDENTITY_BYTES = 16384;
+function recognitionIdentity(source, verified) {
+  const parsed = SourceIdentitySchema.parse(source);
+  if (parsed.provider === "bb.thread") {
+    if (!verified || verified.id !== parsed.id || verified.deletedAt != null)
+      throw new Error("A verified existing thread is required.");
+    return threadIdentity(verified.projectId, verified.id);
+  }
+  if (parsed.provider === "bb.file")
+    throw new Error("Use verifiedFileIdentity with verified frame metadata.");
+  if (parsed.provider === "bb.url") {
+    const href = SafeHrefSchema.parse(parsed.id);
+    return { provider: "url", keys: canonicalizeIdentity({ provider: "url", keys: { href: new URL(href).href } }).keys };
+  }
+  return { provider: "recognition", keys: { provider: parsed.provider, identity: sha256Hex(canonicalJson([parsed.provider, parsed.id])) } };
+}
+function recognitionIdentityRecord(source) {
+  const parsed = SourceIdentitySchema.parse(source);
+  const json = canonicalJson({ provider: parsed.provider, id: parsed.id });
+  if (new TextEncoder().encode(json).length > MAX_RECOGNITION_IDENTITY_BYTES)
+    throw new Error("Recognition identity mapping exceeds its bound.");
+  return json;
+}
+var VerifiedFileTargetSchema = z.discriminatedUnion("kind", [
+  z.strictObject({ kind: z.literal("workspace"), environmentId: fileOwnerId(), path: verifiedFilePath() }),
+  z.strictObject({ kind: z.literal("thread-storage"), threadId: fileOwnerId(), path: verifiedFilePath() })
+]);
+function fileOwnerId() {
+  return z.string().min(1).max(128).regex(/^[A-Za-z0-9_-]+$/);
+}
+function verifiedFilePath() {
+  return z.string().min(1).max(4096).refine((path) => !path.startsWith("/") && !/[\\:%?#\u0000-\u001f\u007f]/u.test(path) && path.split("/").every((part) => part.length > 0 && part !== "." && part !== ".."), "Expected a canonical relative file path.");
+}
+function verifiedFileIdentity(value) {
+  const file = VerifiedFileTargetSchema.parse(value);
+  const owner = file.kind === "workspace" ? file.environmentId : file.threadId;
+  return { provider: "recognition", keys: { provider: "bb.file", identity: sha256Hex(canonicalJson(["bb.file", file.kind, owner, file.path])) } };
+}
+function verifiedFileIdentityRecord(value) {
+  const json = canonicalJson({ provider: "bb.file", verifiedFile: VerifiedFileTargetSchema.parse(value) });
+  if (new TextEncoder().encode(json).length > MAX_RECOGNITION_IDENTITY_BYTES)
+    throw new Error("Verified file mapping exceeds its bound.");
+  return json;
+}
+// src/evidence-v2.ts
+import { z as z2 } from "zod";
+import { ContextBundleV1Schema, SafeHrefSchema as SafeHrefSchema2, CandidateV1Schema, SourceIdentitySchema as SourceIdentitySchema2 } from "@phosphorco/bb-context-recognition";
+var MENTION_V2_LIMITS = Object.freeze({
+  responseBytes: 1048576,
+  inputBytes: 65536,
+  pageSize: 100,
+  cursorBytes: 4096,
+  excerptCodePoints: 320,
+  excerptBytes: 1280,
+  rowBytes: 131072,
+  readMs: 2000,
+  callMs: 5000,
+  lookupMs: 1500,
+  lookupCalls: 8
+});
+var MENTION_V2_METHODS = Object.freeze({ list: "crossReferencesV2ListMentions", resolve: "crossReferencesV2ResolveLookup" });
+var integer = () => z2.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER);
+var time = () => integer().max(8640000000000000);
+var digest = z2.string().regex(/^[a-f0-9]{64}$/);
+var text = (n) => z2.string().max(n).refine((v) => utf8ByteLength(v) <= n, "UTF8 byte bound exceeded.");
+var id = z2.string().min(1).max(256).refine((v) => !/[\p{Cc}]/u.test(v));
+var producer = z2.string().regex(/^[a-z][a-z0-9._-]{0,63}$/);
+var keys = z2.record(z2.string(), z2.string()).refine((v) => Object.keys(v).length <= 16);
+function isUtf16CodePointBoundary(text2, offset) {
+  if (!Number.isSafeInteger(offset) || offset < 0 || offset > text2.length)
+    return false;
+  const before = text2.charCodeAt(offset - 1), after = text2.charCodeAt(offset);
+  return !(before >= 55296 && before <= 56319 && after >= 56320 && after <= 57343);
+}
+function wellFormedUtf16(text2) {
+  for (const point of text2) {
+    const value = point.codePointAt(0);
+    if (value >= 55296 && value <= 57343)
+      return false;
+  }
+  return true;
+}
+var identityShape = { provider: z2.string().min(1).max(64), keys };
+var identityInputV2Schema = z2.strictObject(identityShape).superRefine((v, c) => {
+  try {
+    canonicalizeIdentity(v);
+  } catch {
+    c.addIssue({ code: "custom", message: "Invalid resource identity." });
+  }
+});
+var presentation = z2.object({ label: text(256).min(1), url: text(2048).optional(), detail: text(1024).optional() }).passthrough();
+var resourceOutputV2Schema = z2.object({ ...identityShape, presentation }).passthrough().superRefine((v, c) => {
+  try {
+    canonicalizeResource({ provider: v.provider, keys: v.keys, presentation: { label: v.presentation.label, ...v.presentation.url === undefined ? {} : { url: v.presentation.url }, ...v.presentation.detail === undefined ? {} : { detail: v.presentation.detail } } });
+  } catch {
+    c.addIssue({ code: "custom", message: "Invalid resource." });
+  }
+});
+var safeAuthoredHrefSchema = SafeHrefSchema2.refine((v) => utf8ByteLength(v) <= 16384 && !hasSensitiveUrlParameter(new URL(v, "https://local.invalid")), "Unsafe destination.");
+var mentionQueryV2Schema = z2.discriminatedUnion("kind", [
+  z2.strictObject({ kind: z2.literal("resource"), target: identityInputV2Schema, relation: z2.enum(["self", "github-pr-family"]) }).refine((v) => v.relation === "self" || v.target.provider === "recognition" && v.target.keys.provider === "github" && /^[a-f0-9]{64}$/.test(v.target.keys.identity ?? ""), "Expected a GitHub root identity."),
+  z2.strictObject({ kind: z2.literal("authored-url"), href: safeAuthoredHrefSchema })
+]);
+var listMentionsInputV2Schema = z2.strictObject({
+  version: z2.literal(2),
+  query: mentionQueryV2Schema,
+  source: identityInputV2Schema.optional(),
+  producerPluginId: producer.optional(),
+  pageSize: z2.number().int().min(1).max(100).optional(),
+  cursor: text(4096).optional(),
+  ifSnapshot: digest.optional()
+}).refine((v) => !(v.cursor !== undefined && v.ifSnapshot !== undefined), "Cursor and conditional are exclusive.");
+var spanShape = { start: integer(), end: integer() };
+var spanOutputV2Schema = z2.object(spanShape).passthrough().refine((v) => v.end > v.start);
+var readyShape = {
+  state: z2.literal("ready"),
+  text: z2.string().refine(wellFormedUtf16, "Excerpt text must be well-formed UTF16.").refine((v) => [...v].length <= 320 && utf8ByteLength(v) <= 1280),
+  sourceSpan: spanOutputV2Schema,
+  matchSpan: spanOutputV2Schema,
+  clippedBefore: z2.boolean(),
+  clippedAfter: z2.boolean(),
+  matchClippedBefore: z2.boolean(),
+  matchClippedAfter: z2.boolean(),
+  codecVersion: z2.literal(1)
+};
+var readyCoordinates = (v) => v.matchSpan.end <= v.text.length && v.sourceSpan.end - v.sourceSpan.start === v.text.length && isUtf16CodePointBoundary(v.text, v.matchSpan.start) && isUtf16CodePointBoundary(v.text, v.matchSpan.end);
+var excerptV2Schema = z2.discriminatedUnion("state", [
+  z2.object(readyShape).passthrough().refine(readyCoordinates, "Excerpt bounds must be code-point aligned."),
+  z2.object({ state: z2.literal("unavailable"), reason: z2.enum(["not-materialized", "indivisible-word", "no-eligible-context"]), codecVersion: z2.literal(1) }).passthrough()
+]);
+var excerptRecordV2Schema = z2.discriminatedUnion("state", [
+  z2.strictObject({ ...readyShape, sourceSpan: z2.strictObject(spanShape).refine((v) => v.end > v.start), matchSpan: z2.strictObject(spanShape).refine((v) => v.end > v.start) }).refine(readyCoordinates, "Excerpt bounds must be code-point aligned."),
+  z2.strictObject({ state: z2.literal("unavailable"), reason: z2.enum(["indivisible-word", "no-eligible-context"]), codecVersion: z2.literal(1) })
+]);
+var locatorOutputV2Schema = z2.object({ kind: z2.literal("conversation"), threadId: id, messageId: id, messageSeq: integer(), anchorSeq: integer().nullable(), role: z2.enum(["user", "assistant"]) }).passthrough();
+var recognitionProvenance = z2.object({
+  pluginId: id,
+  origin: z2.enum(["builtin", "contributed"]),
+  confidence: CandidateV1Schema.shape.confidence,
+  recognition: z2.object({
+    basis: z2.enum(["explicit", "text-url", "existing-link", "git-remote", "context"]),
+    explanation: z2.string().min(1).max(200),
+    evidence: z2.object({ span: spanOutputV2Schema.optional(), link: integer().optional(), remote: id.optional() }).passthrough().optional()
+  }).passthrough(),
+  source: SourceIdentitySchema2.passthrough(),
+  authoredHref: safeAuthoredHrefSchema.optional(),
+  verifiedFile: VerifiedFileTargetSchema.optional()
+}).passthrough();
+var verifiedFileOutput = z2.union([
+  z2.object({ kind: z2.literal("workspace"), environmentId: id, path: z2.string().min(1).max(4096) }).passthrough(),
+  z2.object({ kind: z2.literal("thread-storage"), threadId: id, path: z2.string().min(1).max(4096) }).passthrough()
+]);
+var provenanceOutput = recognitionProvenance.extend({ verifiedFile: verifiedFileOutput.optional() });
+var claimShape = {
+  source: resourceOutputV2Schema,
+  target: resourceOutputV2Schema,
+  producerPluginId: producer,
+  graphRevision: integer(),
+  cap: z2.object({ state: z2.enum(["uncapped", "capped", "unknown"]), limit: z2.literal(100).nullable(), sourceHistoryUnknown: z2.boolean().nullable() }).passthrough()
+};
+var knownItem = z2.discriminatedUnion("kind", [
+  z2.object({
+    ...claimShape,
+    kind: z2.literal("occurrence"),
+    evidenceRevision: integer().min(1),
+    occurrenceKey: digest,
+    locator: locatorOutputV2Schema,
+    sourceContentRevision: digest,
+    span: spanOutputV2Schema,
+    excerpt: excerptV2Schema,
+    messageCreatedAt: time(),
+    observedAt: time(),
+    confirmation: z2.enum(["observed", "retained-unconfirmed"]),
+    provenance: provenanceOutput,
+    authoredUrlState: z2.enum(["exact", "not-url", "unknown"])
+  }).passthrough(),
+  z2.object({ ...claimShape, kind: z2.literal("claim-without-evidence"), reason: z2.enum(["legacy", "producer-no-evidence", "not-yet-collected"]), matchBasis: z2.enum(["primary-resource", "primary-url-identity"]) }).passthrough(),
+  z2.object({ ...claimShape, kind: z2.literal("unsupported"), reason: z2.literal("unsupported-format") }).passthrough()
+]);
+var mentionItemV2Schema = z2.unknown().transform((raw, ctx) => {
+  const r = raw;
+  const unknown = (value, known) => typeof value === "string" && !known.includes(value);
+  const future = !!r && typeof r === "object" && (unknown(r.kind, ["occurrence", "claim-without-evidence", "unsupported"]) || r.kind === "occurrence" && (unknown(r.locator?.kind, ["conversation"]) || unknown(r.excerpt?.state, ["ready", "unavailable"]) || typeof r.excerpt?.codecVersion === "number" && r.excerpt.codecVersion !== 1 || unknown(r.confirmation, ["observed", "retained-unconfirmed"]) || unknown(r.authoredUrlState, ["exact", "not-url", "unknown"]) || unknown(r.locator?.role, ["user", "assistant"]) || unknown(r.provenance?.origin, ["builtin", "contributed"]) || unknown(r.provenance?.confidence, ["high", "medium", "low"]) || unknown(r.provenance?.recognition?.basis, ["explicit", "text-url", "existing-link", "git-remote", "context"]) || r.excerpt?.state === "unavailable" && unknown(r.excerpt.reason, ["not-materialized", "indivisible-word", "no-eligible-context"])) || r.kind === "claim-without-evidence" && (unknown(r.reason, ["legacy", "producer-no-evidence", "not-yet-collected"]) || unknown(r.matchBasis, ["primary-resource", "primary-url-identity"])) || unknown(r.cap?.state, ["uncapped", "capped", "unknown"]));
+  if (future && (!r.cap || !z2.object({ state: z2.string(), limit: z2.literal(100).nullable(), sourceHistoryUnknown: z2.boolean().nullable() }).safeParse(r.cap).success)) {
+    ctx.addIssue({ code: "custom", message: "Invalid required claim cap." });
+    return z2.NEVER;
+  }
+  const candidate = future ? {
+    source: r.source,
+    target: r.target,
+    producerPluginId: r.producerPluginId,
+    graphRevision: r.graphRevision,
+    cap: { state: "unknown", limit: null, sourceHistoryUnknown: null },
+    kind: "unsupported",
+    reason: "unsupported-format"
+  } : raw;
+  const parsed = knownItem.safeParse(candidate);
+  if (parsed.success)
+    return parsed.data;
+  ctx.addIssue({ code: "custom", message: "Invalid mention item." });
+  return z2.NEVER;
+});
+var mentionCountsV2Schema = z2.object({ retainedOccurrences: integer(), confirmedOccurrences: integer(), unconfirmedOccurrences: integer(), producerClaims: integer(), indexedSources: integer(), claimsWithoutLocations: integer(), excerptUnavailable: integer() }).passthrough().refine((v) => v.confirmedOccurrences + v.unconfirmedOccurrences === v.retainedOccurrences && v.claimsWithoutLocations <= v.producerClaims && v.indexedSources <= v.producerClaims && v.excerptUnavailable <= v.retainedOccurrences);
+var coverageV2Schema = z2.object({
+  scope: z2.literal("known-sources"),
+  collectionIncomplete: z2.boolean(),
+  retentionLimited: z2.boolean(),
+  capHistoryUnknown: z2.boolean(),
+  legacyClaimsPresent: z2.boolean(),
+  evidenceStateUnknown: z2.boolean(),
+  authoredUrlCoverage: z2.object({ state: z2.enum(["complete-for-known-locations", "partial"]), unknownLocations: integer(), scope: z2.literal("known-locations"), watermark: digest }).passthrough(),
+  reasons: z2.array(text(128)).max(32),
+  reasonsClipped: z2.boolean(),
+  checkedAt: time().nullable()
+}).passthrough();
+var listMentionsOutputV2Schema = z2.discriminatedUnion("status", [
+  z2.object({ version: z2.literal(2), status: z2.literal("page"), snapshot: digest, items: z2.array(mentionItemV2Schema).max(100), counts: mentionCountsV2Schema, coverage: coverageV2Schema, nextCursor: text(4096).nullable() }).passthrough(),
+  z2.object({ version: z2.literal(2), status: z2.literal("not-modified"), snapshot: digest, coverage: coverageV2Schema }).passthrough(),
+  z2.object({ version: z2.literal(2), status: z2.literal("restart"), reason: z2.literal("snapshot-changed"), snapshot: digest }).passthrough(),
+  z2.object({ version: z2.literal(2), status: z2.literal("unavailable"), reason: z2.enum(["index-warming", "read-budget"]), retryable: z2.boolean() }).passthrough()
+]);
+var lookupContextV2Schema = ContextBundleV1Schema.omit({ consumer: true, links: true }).extend({ links: z2.array(z2.strictObject({ href: safeAuthoredHrefSchema })).max(16).optional() });
+var resolveLookupInputV2Schema = z2.strictObject({ version: z2.literal(2), text: z2.string().min(1).max(4096).refine((v) => utf8ByteLength(v) <= 16384), mode: z2.enum(["recognize", "exact-url"]), context: lookupContextV2Schema.optional() });
+var identityOutput = z2.object(identityShape).passthrough().superRefine((v, c) => {
+  try {
+    canonicalizeIdentity({ provider: v.provider, keys: v.keys });
+  } catch {
+    c.addIssue({ code: "custom", message: "Invalid lookup identity." });
+  }
+});
+var queryOutput = z2.discriminatedUnion("kind", [
+  z2.object({ kind: z2.literal("resource"), target: identityOutput, relation: z2.enum(["self", "github-pr-family"]) }).passthrough(),
+  z2.object({ kind: z2.literal("authored-url"), href: safeAuthoredHrefSchema }).passthrough()
+]);
+var resolveLookupOutputV2Schema = z2.object({
+  version: z2.literal(2),
+  state: z2.enum(["ready", "ambiguous", "unrecognized", "incomplete"]),
+  options: z2.array(z2.object({ query: queryOutput, label: text(256), inputSpan: spanOutputV2Schema, basis: z2.enum(["supplier", "native", "stored-codec"]), reasons: z2.array(text(128)).max(16) }).passthrough()).max(8),
+  reasons: z2.array(text(128)).max(16)
+}).passthrough();
+var crossReferencesV2RpcSchemas = {
+  crossReferencesV2ListMentions: { input: listMentionsInputV2Schema, output: listMentionsOutputV2Schema },
+  crossReferencesV2ResolveLookup: { input: resolveLookupInputV2Schema, output: resolveLookupOutputV2Schema }
+};
+var mentionsChangedV2Schema = z2.object({ version: z2.literal(2), producerPluginId: producer, sourceIdentityDigest: digest, graphRevision: integer(), evidenceRevision: integer().nullable(), affectedIdentityDigests: z2.array(digest).max(512), scopeListClipped: z2.boolean() }).passthrough();
+var MENTIONS_V2_CHANNEL = "cross-references-mentions-v2-changed";
+// src/lookup.ts
+function githubLookup(value) {
+  if (!safeAuthoredHrefSchema.safeParse(value).success)
+    return null;
+  let u;
+  try {
+    u = new URL(value);
+  } catch {
+    return null;
+  }
+  if (u.hostname.toLowerCase() !== "github.com" || u.port || u.username || u.password)
+    return null;
+  const p = u.pathname.replace(/\/$/, "").split("/").slice(1);
+  if (!/^[a-z0-9](?:[a-z0-9-]{0,37}[a-z0-9])?$/i.test(p[0] ?? "") || !/^[a-z0-9_.-]{1,100}$/i.test(p[1] ?? "") || [".", ".."].includes(p[1] ?? "") || !["pull", "issues"].includes(p[2] ?? "") || !/^[1-9]\d*$/.test(p[3] ?? "") || !Number.isSafeInteger(Number(p[3])))
+    return null;
+  const repo = `${p[0]}/${p[1]}`.toLowerCase(), n = String(Number(p[3])), kind = p[2] === "pull" ? "pull-request" : "issue";
+  const source = { provider: "github", id: `github.com/${repo}#${n}`, kind };
+  return { source, query: { kind: "resource", target: recognitionIdentity(source), relation: kind === "pull-request" ? "github-pr-family" : "self" }, label: `${repo}#${n}` };
+}
+
+// src/index.ts
 var FORWARD_REFERENCE_CHECK_LIMIT = 10;
 function assertInputRecord(value) {
   if (typeof value !== "object" || value === null || Array.isArray(value)) {
@@ -439,10 +711,10 @@ var namePattern = /^[a-z][a-z0-9._-]{0,63}$/;
 var uuidPattern = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
 var digestPattern = /^[0-9a-f]{64}$/;
 var safeInteger = (schema) => schema.refine(Number.isSafeInteger, { message: "must be a safe integer" });
-var presentationSchema = z.object({
-  label: z.string().max(MAX_PRESENTATION_LABEL_BYTES),
-  detail: z.string().max(MAX_PRESENTATION_DETAIL_BYTES).optional(),
-  url: z.string().max(MAX_PRESENTATION_URL_BYTES).optional()
+var presentationSchema = z3.object({
+  label: z3.string().max(MAX_PRESENTATION_LABEL_BYTES),
+  detail: z3.string().max(MAX_PRESENTATION_DETAIL_BYTES).optional(),
+  url: z3.string().max(MAX_PRESENTATION_URL_BYTES).optional()
 }).strict().superRefine((value, context) => {
   try {
     canonicalizeResource({ provider: "test", keys: { resource: "placeholder" }, presentation: value });
@@ -450,9 +722,9 @@ var presentationSchema = z.object({
     context.addIssue({ code: "custom", message: cause instanceof Error ? cause.message : String(cause) });
   }
 });
-var resourceSchema = z.object({
-  provider: z.string().max(64).regex(namePattern),
-  keys: z.record(z.string().max(64), z.string().max(MAX_KEY_VALUE_BYTES)),
+var resourceSchema = z3.object({
+  provider: z3.string().max(64).regex(namePattern),
+  keys: z3.record(z3.string().max(64), z3.string().max(MAX_KEY_VALUE_BYTES)),
   presentation: presentationSchema
 }).strict().superRefine((value, context) => {
   try {
@@ -461,9 +733,9 @@ var resourceSchema = z.object({
     context.addIssue({ code: "custom", message: cause instanceof Error ? cause.message : String(cause) });
   }
 });
-var resourceIdentitySchema = z.object({
-  provider: z.string().max(64).regex(namePattern),
-  keys: z.record(z.string().max(64), z.string().max(MAX_KEY_VALUE_BYTES))
+var resourceIdentitySchema = z3.object({
+  provider: z3.string().max(64).regex(namePattern),
+  keys: z3.record(z3.string().max(64), z3.string().max(MAX_KEY_VALUE_BYTES))
 }).strict().superRefine((value, context) => {
   try {
     canonicalizeIdentity(value);
@@ -471,19 +743,19 @@ var resourceIdentitySchema = z.object({
     context.addIssue({ code: "custom", message: cause instanceof Error ? cause.message : String(cause) });
   }
 });
-var producerPluginIdSchema = z.string().max(64).regex(namePattern);
-var mutationIdSchema = z.string().max(MAX_MUTATION_ID_BYTES).regex(uuidPattern);
-var revisionSchema = safeInteger(z.number().int());
-var applyProjectionInputSchema = z.object({
-  protocolVersion: z.literal(PROTOCOL_VERSION),
+var producerPluginIdSchema = z3.string().max(64).regex(namePattern);
+var mutationIdSchema = z3.string().max(MAX_MUTATION_ID_BYTES).regex(uuidPattern);
+var revisionSchema = safeInteger(z3.number().int());
+var applyProjectionInputSchema = z3.object({
+  protocolVersion: z3.literal(PROTOCOL_VERSION),
   producerPluginId: producerPluginIdSchema,
   mutationId: mutationIdSchema,
   source: resourceSchema,
   revision: revisionSchema.positive(),
   expectedRevision: revisionSchema.nonnegative(),
-  payloadDigest: z.string().regex(digestPattern),
-  tombstone: z.boolean(),
-  targets: z.array(resourceSchema).max(MAX_TARGETS)
+  payloadDigest: z3.string().regex(digestPattern),
+  tombstone: z3.boolean(),
+  targets: z3.array(resourceSchema).max(MAX_TARGETS)
 }).strict().superRefine((value, context) => {
   try {
     normalizeProjectionCommand(value);
@@ -491,78 +763,78 @@ var applyProjectionInputSchema = z.object({
     context.addIssue({ code: "custom", message: cause instanceof Error ? cause.message : String(cause) });
   }
 });
-var applyProjectionResponseSchema = z.object({
-  outcome: z.enum(["applied", "duplicate", "equal", "stale", "conflict", "cas-mismatch"]),
+var applyProjectionResponseSchema = z3.object({
+  outcome: z3.enum(["applied", "duplicate", "equal", "stale", "conflict", "cas-mismatch"]),
   currentRevision: revisionSchema.nonnegative(),
-  currentDigest: z.string().regex(digestPattern).nullable()
+  currentDigest: z3.string().regex(digestPattern).nullable()
 }).strict();
-var projectionSchema = z.object({
+var projectionSchema = z3.object({
   producerPluginId: producerPluginIdSchema,
   source: resourceSchema,
   revision: revisionSchema.nonnegative(),
   mutationId: mutationIdSchema,
-  payloadDigest: z.string().regex(digestPattern),
-  tombstone: z.boolean(),
-  targets: z.array(resourceSchema).max(MAX_TARGETS)
+  payloadDigest: z3.string().regex(digestPattern),
+  tombstone: z3.boolean(),
+  targets: z3.array(resourceSchema).max(MAX_TARGETS)
 }).strict();
-var getProjectionInputSchema = z.object({
+var getProjectionInputSchema = z3.object({
   producerPluginId: producerPluginIdSchema,
   source: resourceIdentitySchema
 }).strict();
-var getProjectionOutputSchema = z.object({ projection: projectionSchema.nullable() }).strict();
-var backlinkRowSchema = z.object({
+var getProjectionOutputSchema = z3.object({ projection: projectionSchema.nullable() }).strict();
+var backlinkRowSchema = z3.object({
   source: resourceSchema,
   producerPluginId: producerPluginIdSchema,
   revision: revisionSchema.nonnegative(),
   targetPresentation: presentationSchema,
-  position: z.number().int().min(0).max(MAX_TARGETS - 1).refine(Number.isSafeInteger),
+  position: z3.number().int().min(0).max(MAX_TARGETS - 1).refine(Number.isSafeInteger),
   lastSeenAt: revisionSchema.nonnegative().nullable().optional()
 }).strict();
-var listBacklinksInputSchema = z.object({
+var listBacklinksInputSchema = z3.object({
   target: resourceIdentitySchema,
-  pageSize: z.number().int().min(1).max(100).refine(Number.isSafeInteger).optional(),
-  cursor: z.string().max(4096).optional()
+  pageSize: z3.number().int().min(1).max(100).refine(Number.isSafeInteger).optional(),
+  cursor: z3.string().max(4096).optional()
 }).strict();
-var listBacklinksOutputSchema = z.object({
-  rows: z.array(backlinkRowSchema).max(100),
+var listBacklinksOutputSchema = z3.object({
+  rows: z3.array(backlinkRowSchema).max(100),
   total: revisionSchema.nonnegative(),
-  nextCursor: z.string().max(4096).nullable()
+  nextCursor: z3.string().max(4096).nullable()
 }).strict();
-var forwardReferenceRowSchema = z.object({
+var forwardReferenceRowSchema = z3.object({
   target: resourceSchema,
   producerPluginId: producerPluginIdSchema,
   revision: revisionSchema.nonnegative(),
-  position: z.number().int().min(0).max(MAX_TARGETS - 1).refine(Number.isSafeInteger),
+  position: z3.number().int().min(0).max(MAX_TARGETS - 1).refine(Number.isSafeInteger),
   lastSeenAt: revisionSchema.nonnegative().nullable().optional()
 }).strict();
-var listForwardReferencesInputSchema = z.object({
+var listForwardReferencesInputSchema = z3.object({
   source: resourceIdentitySchema,
   producerPluginId: producerPluginIdSchema.optional(),
-  pageSize: z.number().int().min(1).max(100).refine(Number.isSafeInteger).optional(),
-  cursor: z.string().max(4096).optional()
+  pageSize: z3.number().int().min(1).max(100).refine(Number.isSafeInteger).optional(),
+  cursor: z3.string().max(4096).optional()
 }).strict();
-var listForwardReferencesOutputSchema = z.object({
-  rows: z.array(forwardReferenceRowSchema).max(100),
+var listForwardReferencesOutputSchema = z3.object({
+  rows: z3.array(forwardReferenceRowSchema).max(100),
   total: revisionSchema.nonnegative(),
-  nextCursor: z.string().max(4096).nullable()
+  nextCursor: z3.string().max(4096).nullable()
 }).strict();
-var checkForwardReferencesInputSchema = z.object({
+var checkForwardReferencesInputSchema = z3.object({
   source: resourceIdentitySchema,
   producerPluginId: producerPluginIdSchema.optional()
 }).strict();
-var forwardReferenceStatusSchema = z.object({
-  url: z.string().max(MAX_PRESENTATION_URL_BYTES),
-  status: z.number().int().min(100).max(599).nullable(),
-  label: z.string().min(1).max(128)
+var forwardReferenceStatusSchema = z3.object({
+  url: z3.string().max(MAX_PRESENTATION_URL_BYTES),
+  status: z3.number().int().min(100).max(599).nullable(),
+  label: z3.string().min(1).max(128)
 }).strict();
-var checkForwardReferencesOutputSchema = z.array(forwardReferenceStatusSchema).max(FORWARD_REFERENCE_CHECK_LIMIT);
+var checkForwardReferencesOutputSchema = z3.array(forwardReferenceStatusSchema).max(FORWARD_REFERENCE_CHECK_LIMIT);
 var CROSS_REFERENCES_PLUGIN_ID = "cross-references";
 var CROSS_REFERENCES_PROTOCOL = "cross-references";
 var LIMITS = Object.freeze({ callMs: 5000, describeMs: 1000, responseBytes: 1024 * 1024 });
-var describeInputSchema = z.null();
-var describeOutputSchema = z.object({
-  protocol: z.literal(CROSS_REFERENCES_PROTOCOL),
-  versions: z.array(z.number().int().positive().refine(Number.isSafeInteger)).max(16)
+var describeInputSchema = z3.null();
+var describeOutputSchema = z3.object({
+  protocol: z3.literal(CROSS_REFERENCES_PROTOCOL),
+  versions: z3.array(z3.number().int().positive().refine(Number.isSafeInteger)).max(16)
 });
 var crossReferencesRpcSchemas = {
   "crossReferences.describe": { input: describeInputSchema, output: describeOutputSchema },
@@ -572,10 +844,10 @@ var crossReferencesRpcSchemas = {
   listForwardReferences: { input: listForwardReferencesInputSchema, output: listForwardReferencesOutputSchema },
   checkForwardReferences: { input: checkForwardReferencesInputSchema, output: checkForwardReferencesOutputSchema }
 };
-var referenceSnapshotSchema = z.object({
+var referenceSnapshotSchema = z3.object({
   revision: revisionSchema.nonnegative(),
-  targets: z.array(resourceSchema).max(MAX_TARGETS),
-  status: z.object({ state: z.enum(["synced", "pending", "degraded", "blocked"]), error: z.string().max(4096).nullable() })
+  targets: z3.array(resourceSchema).max(MAX_TARGETS),
+  status: z3.object({ state: z3.enum(["synced", "pending", "degraded", "blocked"]), error: z3.string().max(4096).nullable() })
 });
 
 // src/react.tsx

package/dist/testing.js

@@ -1,6 +1,6 @@
 // src/testing.ts
 import { canonicalizeIdentity, normalizeProjectionCommand, resourceIdentityOf } from "./index.js";
-import { createCrossReferencesClient } from "./bb.js";
+import { createCrossReferencesClient, createCrossReferencesV2Client } from "./bb.js";
 async function runCrossReferencesConformance(options) {
   const command = normalizeProjectionCommand(options.command);
   if (command.tombstone || command.targets.length === 0)
@@ -43,6 +43,23 @@ async function runCrossReferencesConformance(options) {
   checks.push("backlinks-acceptance");
   return { level: "source-conformance", pluginId: client.pluginId, checks };
 }
+async function runCrossReferencesV2Conformance(options) {
+  const client = createCrossReferencesV2Client(options.sdk, options.pluginId);
+  await client.describe();
+  const page = await client.listMentions(options.input);
+  if (page.status !== "page")
+    throw new Error("V2 fixture must yield a page.");
+  await options.assertPage(page);
+  const { cursor: _cursor, ifSnapshot: _conditional, ...base } = options.input;
+  const conditional = await client.listMentions({ ...base, ifSnapshot: page.snapshot });
+  if (conditional.status !== "not-modified" || !conditional.coverage.authoredUrlCoverage.watermark)
+    throw new Error("V2 conditional omitted current coverage.");
+  const lookup = await client.resolveLookup(options.lookup);
+  if (!["ready", "ambiguous", "incomplete"].includes(lookup.state) || lookup.options.length === 0)
+    throw new Error("V2 lookup fixture did not resolve.");
+  return { level: "source-conformance", pluginId: client.pluginId, checks: ["describe-v2", "actual-evidence-page", "conditional-current-coverage", "query-normalization"] };
+}
 export {
+  runCrossReferencesV2Conformance,
   runCrossReferencesConformance
 };