@phosphorco/bb-cross-references 0.0.0-stage → 0.1.1

package/dist/bb.js

@@ -0,0 +1,665 @@
+// src/canonical.ts
+import { sha256 } from "@noble/hashes/sha256";
+import { bytesToHex } from "@noble/hashes/utils";
+var PROTOCOL_VERSION = 1;
+var MAX_RESOURCE_KEYS = 32;
+var MAX_KEY_VALUE_BYTES = 512;
+var MAX_KEY_VALUE_MATERIAL_BYTES = 8192;
+var MAX_CANONICAL_IDENTITY_BYTES = 16 * 1024;
+var MAX_PRESENTATION_BYTES = 4 * 1024;
+var MAX_PRESENTATION_LABEL_BYTES = 256;
+var MAX_PRESENTATION_DETAIL_BYTES = 1024;
+var MAX_PRESENTATION_URL_BYTES = 2048;
+var MAX_TARGETS = 256;
+var MAX_PROJECTION_PAYLOAD_BYTES = 256 * 1024;
+var MAX_MUTATION_ID_BYTES = 128;
+var MACHINE_MONITOR_ROUTE = "/plugins/machine-monitor/machine-monitor";
+var NAME_PATTERN = /^[a-z][a-z0-9._-]{0,63}$/;
+var ID_PATTERN = /^[A-Za-z0-9_-]{1,128}$/;
+var UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+var CONTROL_PATTERN = /\p{Cc}/u;
+var encoder = new TextEncoder;
+var SENSITIVE_URL_PARAMETER_NAMES = new Set([
+  "access_token",
+  "api_key",
+  "apikey",
+  "authorization",
+  "code",
+  "cookie",
+  "id_token",
+  "password",
+  "passwd",
+  "refresh_token",
+  "secret",
+  "session",
+  "sessionid",
+  "sid",
+  "sig",
+  "signature",
+  "token",
+  "x-amz-credential",
+  "x-amz-security-token",
+  "x-amz-signature",
+  "x-goog-credential",
+  "x-goog-signature",
+  "x-ms-signature"
+]);
+
+class CrossReferenceValidationError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "CrossReferenceValidationError";
+  }
+}
+function utf8ByteLength(value) {
+  return encoder.encode(value).byteLength;
+}
+function fail(message) {
+  throw new CrossReferenceValidationError(message);
+}
+function isPlainObject(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value))
+    return false;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+function assertPlainObject(value, label) {
+  if (!isPlainObject(value))
+    fail(`${label} must be a plain object.`);
+  if (Reflect.ownKeys(value).some((key) => typeof key !== "string")) {
+    fail(`${label} must not contain symbol keys.`);
+  }
+}
+function assertExactObjectKeys(value, allowed, label) {
+  const allowedSet = new Set(allowed);
+  for (const key of Object.keys(value)) {
+    if (!allowedSet.has(key))
+      fail(`${label} contains unknown field ${key}.`);
+  }
+}
+function assertWellFormedUnicode(value, label) {
+  for (let index = 0;index < value.length; index += 1) {
+    const codeUnit = value.charCodeAt(index);
+    if (codeUnit >= 55296 && codeUnit <= 56319) {
+      const next = value.charCodeAt(index + 1);
+      if (next < 56320 || next > 57343)
+        fail(`${label} contains malformed Unicode.`);
+      index += 1;
+    } else if (codeUnit >= 56320 && codeUnit <= 57343) {
+      fail(`${label} contains malformed Unicode.`);
+    }
+  }
+}
+function assertSafeText(value, label, maxBytes, options = {}) {
+  assertWellFormedUnicode(value, label);
+  if (CONTROL_PATTERN.test(value))
+    fail(`${label} contains a Unicode control character.`);
+  if (options.nonblank === true && value.trim().length === 0)
+    fail(`${label} must not be blank.`);
+  if (utf8ByteLength(value) > maxBytes)
+    fail(`${label} exceeds its ${maxBytes}-byte limit.`);
+  return value;
+}
+function assertName(value, label) {
+  if (typeof value !== "string" || !NAME_PATTERN.test(value)) {
+    fail(`${label} must match ^[a-z][a-z0-9._-]{0,63}$.`);
+  }
+  return value;
+}
+function validateBbId(value, label) {
+  if (typeof value !== "string" || !ID_PATTERN.test(value)) {
+    fail(`${label} must match ^[A-Za-z0-9_-]{1,128}$.`);
+  }
+  return value;
+}
+function validateBbIdentity(provider, keys) {
+  if (provider !== "bb")
+    return;
+  const names = Object.keys(keys);
+  if (names.length === 1 && names[0] === "project") {
+    validateBbId(keys.project, "projectId");
+    return;
+  }
+  if (names.length === 2 && names[0] === "project" && names[1] === "thread") {
+    validateBbId(keys.project, "projectId");
+    validateBbId(keys.thread, "threadId");
+    return;
+  }
+  if (names.length === 2 && names[0] === "page" && names[1] === "plugin" && keys.page === "machine-monitor" && keys.plugin === "machine-monitor") {
+    return;
+  }
+  fail("provider bb must use a v1 project, thread, or Machine Monitor identity.");
+}
+function hasSensitiveParameterName(params) {
+  for (const name of params.keys()) {
+    if (SENSITIVE_URL_PARAMETER_NAMES.has(name.toLowerCase()))
+      return true;
+  }
+  return false;
+}
+function validateUrlIdentity(provider, keys) {
+  if (provider !== "url")
+    return;
+  const names = Object.keys(keys);
+  if (names.length !== 1 || names[0] !== "href")
+    fail("provider url must use exactly the href key.");
+  const href = keys.href;
+  let parsed;
+  try {
+    parsed = new URL(href);
+  } catch {
+    fail("url href must be a valid HTTP(S) URL.");
+  }
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:")
+    fail("url href must use HTTP(S).");
+  if (parsed.username !== "" || parsed.password !== "")
+    fail("url href must not contain credentials.");
+  if (hasSensitiveParameterName(parsed.searchParams) || parsed.hash.startsWith("#") && hasSensitiveParameterName(new URLSearchParams(parsed.hash.slice(1)))) {
+    fail("url href must not contain credential-shaped query or fragment parameters.");
+  }
+  if (parsed.href !== href)
+    fail("url href must use canonical URL serialization.");
+}
+function validateProducerPluginId(value) {
+  return assertName(value, "producerPluginId");
+}
+function validateMutationId(value) {
+  if (typeof value !== "string" || utf8ByteLength(value) > MAX_MUTATION_ID_BYTES || !UUID_PATTERN.test(value)) {
+    fail("mutationId must be a lower-case UUID string.");
+  }
+  return value;
+}
+function validateRevision(value, label, minimum) {
+  if (!Number.isSafeInteger(value) || value < minimum) {
+    fail(`${label} must be a safe integer >= ${minimum}.`);
+  }
+  return value;
+}
+function validateDigest(value, label = "payloadDigest") {
+  if (typeof value !== "string" || !/^[0-9a-f]{64}$/.test(value)) {
+    fail(`${label} must be lower-case SHA-256 hex.`);
+  }
+  return value;
+}
+function canonicalizeKeyMap(value) {
+  assertPlainObject(value, "keys");
+  const keyNames = Object.keys(value);
+  if (keyNames.length < 1 || keyNames.length > MAX_RESOURCE_KEYS) {
+    fail(`keys must contain between 1 and ${MAX_RESOURCE_KEYS} entries.`);
+  }
+  let materialBytes = 0;
+  const entries = keyNames.map((key) => {
+    assertName(key, "key name");
+    const rawValue = value[key];
+    if (typeof rawValue !== "string")
+      fail(`key ${key} value must be a string.`);
+    const normalizedValue = rawValue.normalize("NFC");
+    const safeValue = assertSafeText(normalizedValue, `key ${key} value`, MAX_KEY_VALUE_BYTES, { nonblank: true });
+    materialBytes += utf8ByteLength(key) + utf8ByteLength(safeValue);
+    return [key, safeValue];
+  });
+  if (materialBytes > MAX_KEY_VALUE_MATERIAL_BYTES) {
+    fail(`combined key/value material exceeds its ${MAX_KEY_VALUE_MATERIAL_BYTES}-byte limit.`);
+  }
+  entries.sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0);
+  const keys = Object.fromEntries(entries);
+  return { keys, canonicalKeysJson: JSON.stringify(keys) };
+}
+function canonicalizeIdentity(value) {
+  assertPlainObject(value, "resource identity");
+  assertExactObjectKeys(value, ["provider", "keys"], "resource identity");
+  const provider = assertName(value.provider, "provider");
+  const { keys, canonicalKeysJson } = canonicalizeKeyMap(value.keys);
+  validateBbIdentity(provider, keys);
+  validateUrlIdentity(provider, keys);
+  const identityObject = { provider, keys };
+  const canonicalIdentityJson = JSON.stringify(identityObject);
+  if (utf8ByteLength(canonicalIdentityJson) > MAX_CANONICAL_IDENTITY_BYTES) {
+    fail(`canonical identity exceeds its ${MAX_CANONICAL_IDENTITY_BYTES}-byte limit.`);
+  }
+  return {
+    provider,
+    keys,
+    canonicalKeysJson,
+    canonicalIdentityJson,
+    identityDigest: sha256Hex(canonicalIdentityJson)
+  };
+}
+function canonicalizePresentation(value) {
+  assertPlainObject(value, "presentation");
+  assertExactObjectKeys(value, ["label", "detail", "url"], "presentation");
+  if (typeof value.label !== "string")
+    fail("presentation.label must be a string.");
+  const label = assertSafeText(value.label, "presentation.label", MAX_PRESENTATION_LABEL_BYTES, { nonblank: true });
+  const presentation = { label };
+  if (value.detail !== undefined) {
+    if (typeof value.detail !== "string")
+      fail("presentation.detail must be a string when supplied.");
+    presentation.detail = assertSafeText(value.detail, "presentation.detail", MAX_PRESENTATION_DETAIL_BYTES, { nonblank: true });
+  }
+  if (value.url !== undefined) {
+    if (typeof value.url !== "string")
+      fail("presentation.url must be a string when supplied.");
+    const url = assertSafeText(value.url, "presentation.url", MAX_PRESENTATION_URL_BYTES, { nonblank: true });
+    if (url.startsWith("/") && !url.startsWith("//") && !url.includes("\\")) {
+      presentation.url = url;
+    } else if (url.startsWith("http://") || url.startsWith("https://")) {
+      try {
+        const parsed = new URL(url);
+        if (parsed.protocol !== "http:" && parsed.protocol !== "https:")
+          fail("presentation.url must use http or https.");
+        presentation.url = url;
+      } catch {
+        fail("presentation.url must be a valid http or https URL.");
+      }
+    } else {
+      fail("presentation.url must be a same-origin route or an http(s) URL.");
+    }
+  }
+  const presentationJson = JSON.stringify(presentation);
+  if (utf8ByteLength(presentationJson) > MAX_PRESENTATION_BYTES) {
+    fail(`presentation exceeds its ${MAX_PRESENTATION_BYTES}-byte limit.`);
+  }
+  return { presentation, presentationJson };
+}
+function canonicalizeResource(value) {
+  assertPlainObject(value, "resource");
+  assertExactObjectKeys(value, ["provider", "keys", "presentation"], "resource");
+  const identity = canonicalizeIdentity({ provider: value.provider, keys: value.keys });
+  const presentation = canonicalizePresentation(value.presentation);
+  if (identity.provider === "url" && presentation.presentation.url !== identity.keys.href) {
+    fail("provider url presentation.url must equal its canonical href identity.");
+  }
+  return { ...identity, ...presentation };
+}
+function resourceIdentityOf(resource) {
+  return { provider: resource.provider, keys: resource.keys };
+}
+function projectIdentity(projectId) {
+  return { provider: "bb", keys: { project: validateBbId(projectId, "projectId") } };
+}
+function threadIdentity(projectId, threadId) {
+  return {
+    provider: "bb",
+    keys: {
+      project: validateBbId(projectId, "projectId"),
+      thread: validateBbId(threadId, "threadId")
+    }
+  };
+}
+function machineMonitorIdentity() {
+  return { provider: "bb", keys: { page: "machine-monitor", plugin: "machine-monitor" } };
+}
+function projectResource(projectId, presentation) {
+  return { ...projectIdentity(projectId), presentation };
+}
+function threadResource(projectId, threadId, presentation) {
+  return { ...threadIdentity(projectId, threadId), presentation };
+}
+function machineMonitorResource(presentation = {
+  label: "Machine Monitor",
+  url: MACHINE_MONITOR_ROUTE
+}) {
+  return { ...machineMonitorIdentity(), presentation };
+}
+function serializeResource(resource) {
+  return {
+    provider: resource.provider,
+    keys: resource.keys,
+    presentation: resource.presentation
+  };
+}
+function sha256Hex(value) {
+  return bytesToHex(sha256(encoder.encode(value)));
+}
+function projectionPayloadJson(producerPluginId, source, tombstone, targets) {
+  const payload = {
+    protocolVersion: PROTOCOL_VERSION,
+    producerPluginId,
+    source: serializeResource(source),
+    tombstone,
+    targets: targets.map(serializeResource)
+  };
+  const json = JSON.stringify(payload);
+  if (utf8ByteLength(json) > MAX_PROJECTION_PAYLOAD_BYTES) {
+    fail(`projection payload exceeds its ${MAX_PROJECTION_PAYLOAD_BYTES}-byte limit.`);
+  }
+  return json;
+}
+function projectionPayloadDigest(producerPluginId, source, tombstone, targets) {
+  return sha256Hex(projectionPayloadJson(producerPluginId, source, tombstone, targets));
+}
+function isExactBbThreadResource(resource) {
+  const keys = Object.keys(resource.keys);
+  return resource.provider === "bb" && keys.length === 2 && keys[0] === "project" && keys[1] === "thread" && ID_PATTERN.test(resource.keys.project) && ID_PATTERN.test(resource.keys.thread);
+}
+function isUrlResource(resource) {
+  return resource.provider === "url" && Object.keys(resource.keys).length === 1 && resource.keys.href != null && resource.presentation.url === resource.keys.href;
+}
+function normalizeThreadOrUrlReference(target) {
+  const resource = canonicalizeResource(target);
+  if (!isExactBbThreadResource(resource) && !isUrlResource(resource)) {
+    throw new CrossReferenceValidationError("References must be exact BB threads or safe HTTP(S) URLs.");
+  }
+  if (isExactBbThreadResource(resource) && resource.presentation.url !== undefined && resource.presentation.url !== `/projects/${resource.keys.project}/threads/${resource.keys.thread}` && resource.presentation.url !== `/threads/${resource.keys.thread}`) {
+    throw new CrossReferenceValidationError("Native thread presentation URL must match its thread identity.");
+  }
+  return resource;
+}
+function urlResource(href, presentation) {
+  const canonicalHref = new URL(href).href;
+  return { provider: "url", keys: { href: canonicalHref }, presentation: { ...presentation, url: canonicalHref } };
+}
+var MAX_REFERENCE_URL_BYTES = 512;
+var MAX_REFERENCE_LABEL_BYTES = 256;
+function hasSensitiveUrlParameter(url) {
+  return hasSensitiveParameterName(url.searchParams) || url.hash.startsWith("#") && hasSensitiveParameterName(new URLSearchParams(url.hash.slice(1)));
+}
+function referenceLabelError(value) {
+  if (value.trim().length === 0)
+    return "Give this external reference a name.";
+  if (utf8ByteLength(value) > MAX_REFERENCE_LABEL_BYTES) {
+    return `Reference names are limited to ${MAX_REFERENCE_LABEL_BYTES} UTF-8 bytes.`;
+  }
+  return null;
+}
+
+// src/index.ts
+import { z } from "zod";
+var FORWARD_REFERENCE_CHECK_LIMIT = 10;
+function assertInputRecord(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new CrossReferenceValidationError("projection input must be an object.");
+  }
+  const fields = Object.keys(value).sort();
+  if (fields.join(",") !== "expectedRevision,mutationId,payloadDigest,producerPluginId,protocolVersion,revision,source,targets,tombstone") {
+    throw new CrossReferenceValidationError("projection input fields are invalid.");
+  }
+}
+function normalizeProjectionCommand(input) {
+  assertInputRecord(input);
+  if (input.protocolVersion !== PROTOCOL_VERSION) {
+    throw new CrossReferenceValidationError(`protocolVersion must be ${PROTOCOL_VERSION}.`);
+  }
+  const producerPluginId = validateProducerPluginId(input.producerPluginId);
+  const mutationId = validateMutationId(input.mutationId);
+  const revision = validateRevision(input.revision, "revision", 1);
+  const expectedRevision = validateRevision(input.expectedRevision, "expectedRevision", 0);
+  if (typeof input.tombstone !== "boolean") {
+    throw new CrossReferenceValidationError("tombstone must be a boolean.");
+  }
+  if (!Array.isArray(input.targets) || input.targets.length > MAX_TARGETS) {
+    throw new CrossReferenceValidationError(`targets must contain at most ${MAX_TARGETS} resources.`);
+  }
+  const source = canonicalizeResource(input.source);
+  const targets = input.targets.map((target) => canonicalizeResource(target));
+  const identitySet = new Set;
+  for (const target of targets) {
+    if (identitySet.has(target.canonicalIdentityJson)) {
+      throw new CrossReferenceValidationError("targets must not contain duplicate resource identities.");
+    }
+    identitySet.add(target.canonicalIdentityJson);
+  }
+  if (input.tombstone && targets.length !== 0) {
+    throw new CrossReferenceValidationError("a tombstone must have an empty target list.");
+  }
+  const payloadJson = projectionPayloadJson(producerPluginId, source, input.tombstone, targets);
+  const computedPayloadDigest = sha256Hex(payloadJson);
+  const payloadDigest = validateDigest(input.payloadDigest);
+  if (payloadDigest !== computedPayloadDigest) {
+    throw new CrossReferenceValidationError("payloadDigest does not match the canonical projection payload.");
+  }
+  return {
+    protocolVersion: PROTOCOL_VERSION,
+    producerPluginId,
+    mutationId,
+    source,
+    revision,
+    expectedRevision,
+    payloadDigest,
+    tombstone: input.tombstone,
+    targets,
+    payloadJson,
+    computedPayloadDigest
+  };
+}
+function normalizeIdentityInput(input) {
+  return canonicalizeIdentity(input);
+}
+function defaultPageSize(pageSize) {
+  if (pageSize === undefined)
+    return 25;
+  const validated = validateRevision(pageSize, "pageSize", 1);
+  if (validated > 100) {
+    throw new CrossReferenceValidationError("pageSize must be between 1 and 100.");
+  }
+  return validated;
+}
+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()
+}).strict().superRefine((value, context) => {
+  try {
+    canonicalizeResource({ provider: "test", keys: { resource: "placeholder" }, presentation: value });
+  } catch (cause) {
+    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)),
+  presentation: presentationSchema
+}).strict().superRefine((value, context) => {
+  try {
+    canonicalizeResource(value);
+  } catch (cause) {
+    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))
+}).strict().superRefine((value, context) => {
+  try {
+    canonicalizeIdentity(value);
+  } catch (cause) {
+    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),
+  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)
+}).strict().superRefine((value, context) => {
+  try {
+    normalizeProjectionCommand(value);
+  } catch (cause) {
+    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"]),
+  currentRevision: revisionSchema.nonnegative(),
+  currentDigest: z.string().regex(digestPattern).nullable()
+}).strict();
+var projectionSchema = z.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)
+}).strict();
+var getProjectionInputSchema = z.object({
+  producerPluginId: producerPluginIdSchema,
+  source: resourceIdentitySchema
+}).strict();
+var getProjectionOutputSchema = z.object({ projection: projectionSchema.nullable() }).strict();
+var backlinkRowSchema = z.object({
+  source: resourceSchema,
+  producerPluginId: producerPluginIdSchema,
+  revision: revisionSchema.nonnegative(),
+  targetPresentation: presentationSchema,
+  position: z.number().int().min(0).max(MAX_TARGETS - 1).refine(Number.isSafeInteger),
+  lastSeenAt: revisionSchema.nonnegative().nullable().optional()
+}).strict();
+var listBacklinksInputSchema = z.object({
+  target: resourceIdentitySchema,
+  pageSize: z.number().int().min(1).max(100).refine(Number.isSafeInteger).optional(),
+  cursor: z.string().max(4096).optional()
+}).strict();
+var listBacklinksOutputSchema = z.object({
+  rows: z.array(backlinkRowSchema).max(100),
+  total: revisionSchema.nonnegative(),
+  nextCursor: z.string().max(4096).nullable()
+}).strict();
+var forwardReferenceRowSchema = z.object({
+  target: resourceSchema,
+  producerPluginId: producerPluginIdSchema,
+  revision: revisionSchema.nonnegative(),
+  position: z.number().int().min(0).max(MAX_TARGETS - 1).refine(Number.isSafeInteger),
+  lastSeenAt: revisionSchema.nonnegative().nullable().optional()
+}).strict();
+var listForwardReferencesInputSchema = z.object({
+  source: resourceIdentitySchema,
+  producerPluginId: producerPluginIdSchema.optional(),
+  pageSize: z.number().int().min(1).max(100).refine(Number.isSafeInteger).optional(),
+  cursor: z.string().max(4096).optional()
+}).strict();
+var listForwardReferencesOutputSchema = z.object({
+  rows: z.array(forwardReferenceRowSchema).max(100),
+  total: revisionSchema.nonnegative(),
+  nextCursor: z.string().max(4096).nullable()
+}).strict();
+var checkForwardReferencesInputSchema = z.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)
+}).strict();
+var checkForwardReferencesOutputSchema = z.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 crossReferencesRpcSchemas = {
+  "crossReferences.describe": { input: describeInputSchema, output: describeOutputSchema },
+  applyProjection: { input: applyProjectionInputSchema, output: applyProjectionResponseSchema },
+  getProjection: { input: getProjectionInputSchema, output: getProjectionOutputSchema },
+  listBacklinks: { input: listBacklinksInputSchema, output: listBacklinksOutputSchema },
+  listForwardReferences: { input: listForwardReferencesInputSchema, output: listForwardReferencesOutputSchema },
+  checkForwardReferences: { input: checkForwardReferencesInputSchema, output: checkForwardReferencesOutputSchema }
+};
+var referenceSnapshotSchema = z.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() })
+});
+
+// src/bb.ts
+import { z as z2 } from "zod";
+class CrossReferencesProtocolError extends Error {
+  code = "incompatible_protocol";
+  constructor(message) {
+    super(message);
+    this.name = "CrossReferencesProtocolError";
+  }
+}
+function budget(value, maximum) {
+  if (value === undefined)
+    return maximum;
+  if (!Number.isFinite(value) || value <= 0 || value > maximum)
+    throw new RangeError(`Budget must be > 0 and <= ${maximum}.`);
+  return value;
+}
+function createCrossReferencesClient(sdk, targetPluginId = CROSS_REFERENCES_PLUGIN_ID, options = {}) {
+  const pluginId = validateProducerPluginId(targetPluginId);
+  const callMs = budget(options.callMs, LIMITS.callMs);
+  const describeMs = budget(options.describeMs, LIMITS.describeMs);
+  async function call(method, input, inputSchema, outputSchema, signal) {
+    const parsedInput = inputSchema.parse(input);
+    if (signal?.aborted)
+      throw signal.reason ?? new DOMException("Request aborted", "AbortError");
+    const controller = new AbortController;
+    let rejectCancellation = () => {};
+    const cancelled = new Promise((_, reject) => {
+      rejectCancellation = reject;
+    });
+    const abort = () => {
+      const reason = signal?.reason ?? new DOMException("Request aborted", "AbortError");
+      rejectCancellation(reason);
+      controller.abort(reason);
+    };
+    signal?.addEventListener("abort", abort, { once: true });
+    const timer = setTimeout(() => {
+      const reason = Object.assign(new Error(`Cross References ${method} timed out`), { name: "TimeoutError", code: "timeout" });
+      rejectCancellation(reason);
+      controller.abort(reason);
+    }, method === "crossReferences.describe" ? describeMs : callMs);
+    try {
+      const value = await Promise.race([
+        sdk.plugins.callRpc({ pluginId, method, input: JSON.parse(JSON.stringify(parsedInput)), outputSchema: z2.unknown(), signal: controller.signal }),
+        cancelled
+      ]);
+      const json = JSON.stringify(value);
+      if (json === undefined || utf8ByteLength(json) > LIMITS.responseBytes)
+        throw new CrossReferencesProtocolError("RPC result exceeds its canonical JSON byte limit or is not JSON.");
+      return outputSchema.parse(value);
+    } finally {
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", abort);
+    }
+  }
+  function operation(method, input, signal) {
+    const schemas = crossReferencesRpcSchemas[method];
+    return call(method, input, schemas.input, schemas.output, signal);
+  }
+  return {
+    pluginId,
+    async describe(signal) {
+      const schemas = crossReferencesRpcSchemas["crossReferences.describe"];
+      try {
+        const description = await call("crossReferences.describe", null, schemas.input, schemas.output, signal);
+        if (!description.versions.includes(1))
+          throw new CrossReferencesProtocolError("Cross References does not support wire version 1.");
+        return { protocol: CROSS_REFERENCES_PROTOCOL, version: 1, legacy: false };
+      } catch (error) {
+        if (typeof error === "object" && error !== null && "code" in error && error.code === "unknown_method") {
+          return { protocol: CROSS_REFERENCES_PROTOCOL, version: 1, legacy: true };
+        }
+        throw error;
+      }
+    },
+    applyProjection: (input, signal) => operation("applyProjection", input, signal),
+    getProjection: (input, signal) => operation("getProjection", input, signal),
+    listBacklinks: (input, signal) => operation("listBacklinks", input, signal),
+    listForwardReferences: (input, signal) => operation("listForwardReferences", input, signal),
+    checkForwardReferences: (input, signal) => operation("checkForwardReferences", input, signal)
+  };
+}
+export {
+  createCrossReferencesClient,
+  CrossReferencesProtocolError
+};