sentinelayer-cli 0.46.5 → 0.48.0

package/src/engram/contracts/capability.js

@@ -0,0 +1,377 @@
+/**
+ * ENGRAM §EW02 — Capability contract (R04 skills, R14 parallelism).
+ *
+ * Source/capability versions and tenant scope are required — no inferred
+ * backend endpoints from screenshots (ticket 73ead329 mandatory constraints).
+ *
+ * This module codifies:
+ *   - Capability versioning: every source and capability declares its version
+ *   - Tenant scoping: every graph consumer operates within a tenant
+ *   - Protocol capability negotiation: what two parties agree they can do
+ *   - Unknown/unsupported/stale errors: typed, with evidence addresses
+ *   - Pagination: cursor-based pagination for evidence lists
+ *   - Migration policy: version compatibility declarations
+ *
+ * All schemas are strict: extra fields are rejected (luna-judge P2 finding).
+ * Negotiation validates inputs on every path and returns validated results.
+ */
+
+import { z } from "zod";
+import { nonblankIdentitySchema } from "./identity.js";
+
+/**
+ * A capability version identifier.
+ * Format: <name>@<semver> (e.g. "engram-graph@1.0.0")
+ */
+const CAPABILITY_NAME_RE = /^[a-z][a-z0-9_-]{0,47}$/;
+const CAPABILITY_VERSION_RE = /^([a-z][a-z0-9_-]{0,47})@(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$/;
+
+export const capabilityVersionSchema = z.string().regex(
+  CAPABILITY_VERSION_RE,
+  { message: "capability version must match <name>@<semver>" },
+);
+
+/** The canonical tenant key used by sources, entries and negotiation. */
+export const tenantScopeSchema = nonblankIdentitySchema;
+
+/** Optional structured tenant metadata; it is not a wire tenant key. */
+export const tenantScopeDescriptorSchema = z.object({
+  tenantId: nonblankIdentitySchema.max(128),
+  namespace: nonblankIdentitySchema.max(256).optional(),
+  environment: z.enum(["production", "staging", "development", "sandbox"]).optional(),
+}).strict();
+
+/**
+ * A source descriptor: identifies where an assertion or capability originated.
+ */
+export const sourceDescriptorSchema = z.object({
+  sourceId: nonblankIdentitySchema,
+  sourceType: z.enum(["adapter", "ingest", "derived", "external", "manual"]),
+  version: capabilityVersionSchema,
+  tenantScope: tenantScopeSchema,
+  endpoint: z.string().url().optional(),
+}).strict();
+
+/**
+ * Valid capability status values for server entries.
+ */
+const CAPABILITY_STATUS = z.enum(["supported", "deprecated", "experimental", "unknown", "unsupported", "stale"]);
+
+/**
+ * A single capability entry: what a source can do, at what version.
+ */
+export const capabilityEntrySchema = z.object({
+  capability: z.string().regex(CAPABILITY_NAME_RE),
+  version: capabilityVersionSchema,
+  source: sourceDescriptorSchema,
+  status: CAPABILITY_STATUS,
+  evidenceAddress: z.string().optional(),
+  deprecatesAt: z.string().datetime().optional(),
+  migratesTo: capabilityVersionSchema.optional(),
+}).strict().superRefine((entry, ctx) => {
+  for (const field of ["version", "migratesTo"]) {
+    if (entry[field] && !versionNameMatches(entry.capability, entry[field])) {
+      ctx.addIssue({ code: "custom", path: [field], message: `${field} name must match capability` });
+    }
+  }
+});
+
+/**
+ * Protocol capability negotiation result.
+ */
+export const negotiationResultSchema = z.object({
+  capability: z.string().regex(CAPABILITY_NAME_RE),
+  clientVersion: capabilityVersionSchema,
+  serverVersion: capabilityVersionSchema.optional(),
+  negotiatedVersion: capabilityVersionSchema.optional(),
+  tenantScope: tenantScopeSchema.optional(),
+  result: z.enum(["matched", "upgraded", "downgraded", "incompatible", "unknown"]),
+  reason: z.string().optional(),
+  evidenceAddress: z.string().optional(),
+}).strict().superRefine((result, ctx) => {
+  for (const field of ["clientVersion", "serverVersion", "negotiatedVersion"]) {
+    if (result[field] && !versionNameMatches(result.capability, result[field])) {
+      ctx.addIssue({ code: "custom", path: [field], message: `${field} name must match capability` });
+    }
+  }
+  const usable = ["matched", "upgraded", "downgraded"].includes(result.result);
+  if (usable) {
+    if (!result.tenantScope) {
+      ctx.addIssue({ code: "custom", path: ["tenantScope"], message: "usable negotiation requires requesting tenant scope" });
+    }
+    if (!result.serverVersion || !result.negotiatedVersion || result.negotiatedVersion !== result.serverVersion) {
+      ctx.addIssue({ code: "custom", path: ["negotiatedVersion"], message: "usable negotiation must identify the server version" });
+    }
+    if (result.serverVersion) {
+      const client = parseCapVersion(result.clientVersion);
+      const server = parseCapVersion(result.serverVersion);
+      if (client && server) {
+        if (client[1] !== server[1]) {
+          ctx.addIssue({ code: "custom", path: ["result"], message: "usable negotiation requires a matching major version" });
+        }
+        const order = server[2] === client[2]
+          ? (server[3] > client[3] ? 1 : server[3] < client[3] ? -1 : 0)
+          : (server[2] > client[2] ? 1 : -1);
+        if ((result.result === "matched" && order !== 0) ||
+            (result.result === "upgraded" && order <= 0) ||
+            (result.result === "downgraded" && order >= 0)) {
+          ctx.addIssue({ code: "custom", path: ["result"], message: "negotiation result must match version order" });
+        }
+      }
+    }
+  } else if (result.negotiatedVersion) {
+    ctx.addIssue({ code: "custom", path: ["negotiatedVersion"], message: "unusable negotiation cannot grant a version" });
+  }
+});
+
+/**
+ * Pagination cursor for evidence lists.
+ */
+export const paginationSchema = z.object({
+  cursor: z.string().optional(),
+  limit: z.number().int().min(1).max(1000).optional(),
+  nextCursor: z.string().optional(),
+  hasMore: z.boolean().optional(),
+  total: z.number().int().nonnegative().optional(),
+}).strict().refine(
+  (page) => !page.hasMore || !!page.nextCursor,
+  { message: "hasMore requires nextCursor", path: ["nextCursor"] },
+);
+
+/**
+ * Migration policy: declares compatibility between capability versions.
+ */
+export const migrationPolicySchema = z.object({
+  capability: z.string().regex(CAPABILITY_NAME_RE),
+  fromVersion: capabilityVersionSchema,
+  toVersion: capabilityVersionSchema,
+  compatibility: z.enum(["compatible", "breaking", "additive"]),
+  migrationNotes: z.string().optional(),
+  createdAt: z.string().datetime(),
+}).strict().superRefine((policy, ctx) => {
+  for (const field of ["fromVersion", "toVersion"]) {
+    if (!versionNameMatches(policy.capability, policy[field])) {
+      ctx.addIssue({ code: "custom", path: [field], message: `${field} name must match capability` });
+    }
+  }
+});
+
+/**
+ * Error types for capability operations.
+ */
+export class CapabilityError extends Error {
+  constructor(message, code, evidence) {
+    super(message);
+    this.name = "CapabilityError";
+    this.code = code;
+    this.evidence = evidence || null;
+  }
+}
+
+export function unknownCapability(capability, evidence) {
+  return new CapabilityError(
+    `capability "${capability}" is unknown or not registered`,
+    "unknown_capability",
+    evidence,
+  );
+}
+
+export function unsupportedCapability(capability, version, reason, evidence) {
+  return new CapabilityError(
+    `capability "${capability}@${version}" is unsupported: ${reason || "no reason given"}`,
+    "unsupported_capability",
+    evidence,
+  );
+}
+
+export function staleCapability(capability, version, asOf, evidence) {
+  return new CapabilityError(
+    `capability "${capability}@${version}" is stale (asOf ${asOf}); refresh required`,
+    "stale_capability",
+    evidence,
+  );
+}
+
+/**
+ * Parse a semver tuple from a capability version string.
+ * @param {string} capVersion — e.g. "engram-graph@1.2.3"
+ * @returns {[string, bigint, bigint, bigint]|null} — [name, major, minor, patch]
+ */
+function parseCapVersion(capVersion) {
+  const match = typeof capVersion === "string" && CAPABILITY_VERSION_RE.exec(capVersion);
+  if (!match) return null;
+  return [match[1], BigInt(match[2]), BigInt(match[3]), BigInt(match[4])];
+}
+
+/**
+ * Validate that a server entry's version name binds to the stated capability.
+ */
+function versionNameMatches(capabilityName, versionString) {
+  const parts = parseCapVersion(versionString);
+  if (!parts) return false;
+  return parts[0] === capabilityName;
+}
+
+/**
+ * Negotiate a protocol capability between client and server.
+ *
+ * F7/F8 fixes:
+ * - Stale capabilities return "incompatible" with NO negotiatedVersion
+ * - Unknown capabilities return "unknown" immediately, no version comparison
+ * - Validates server entries and binds version names to the capability
+ * - Misspelled statuses are rejected (invalid status → incompatible)
+ * - Every path returns a negotiationResultSchema-valid result or a typed error
+ *
+ * @param {object} params
+ * @param {string} params.capability
+ * @param {string} params.clientVersion
+ * @param {string} params.tenantScope — requesting tenant; caller must authenticate it
+ * @param {Array<{capability: string, version: string, status: string}>} params.serverCapabilities
+ * @returns {object} negotiationResultSchema-shaped result
+ */
+export function negotiateCapability({ capability, clientVersion, tenantScope, serverCapabilities = [] } = {}) {
+  // All failure paths retain a schema-valid result; malformed caller values
+  // cannot leak into the output or grant a usable negotiated version.
+  const safeCapability = typeof capability === "string" && CAPABILITY_NAME_RE.test(capability)
+    ? capability : "unknown-cap";
+  const clientParts = parseCapVersion(clientVersion);
+  const safeClientVersion = clientParts?.[0] === safeCapability
+    ? clientVersion : `${safeCapability}@0.0.0`;
+  const requestedTenant = tenantScopeSchema.safeParse(tenantScope).success
+    ? tenantScope : undefined;
+  const makeResult = (overrides) => negotiationResultSchema.parse({
+    capability: safeCapability,
+    clientVersion: safeClientVersion,
+    ...(requestedTenant ? { tenantScope: requestedTenant } : {}),
+    result: "incompatible",
+    ...overrides,
+  });
+
+  if (safeCapability !== capability) {
+    return makeResult({ reason: "capability is required and must be a valid name" });
+  }
+  if (!clientParts) {
+    return makeResult({ reason: "clientVersion is not a valid capability version" });
+  }
+  if (clientParts[0] !== capability) {
+    return makeResult({
+      reason: `clientVersion name "${clientParts[0]}" does not match capability "${capability}"`,
+    });
+  }
+  if (!requestedTenant) {
+    return makeResult({ reason: "requesting tenantScope is required for capability negotiation" });
+  }
+  if (!Array.isArray(serverCapabilities)) {
+    return makeResult({ result: "unknown", reason: "serverCapabilities must be an array" });
+  }
+
+  const matchingEntries = serverCapabilities.filter((entry) =>
+    entry && typeof entry === "object" && entry.capability === capability &&
+    entry.source?.tenantScope === requestedTenant);
+
+  if (matchingEntries.length === 0) {
+    return makeResult({ result: "unknown", reason: `capability "${capability}" is not registered for this tenant` });
+  }
+  // A list with multiple claims for one capability and tenant cannot choose
+  // authority by array order. A selection policy for version sets belongs in a
+  // later protocol version; this contract fails closed until one is defined.
+  if (matchingEntries.length > 1) {
+    return makeResult({ reason: `capability "${capability}" has ambiguous server entries for this tenant` });
+  }
+  const serverCap = matchingEntries[0];
+
+  // Validate the server entry against the full capabilityEntrySchema.
+  // This ensures source, tenantScope, and all required fields are present
+  // before negotiating. An entry missing source/tenant is not a valid capability.
+  const entryResult = capabilityEntrySchema.safeParse(serverCap);
+  if (!entryResult.success) {
+    return makeResult({
+      result: "unknown",
+      reason: `capability "${capability}" server entry is invalid: ${entryResult.error.issues.map((i) => i.message).join("; ")}`,
+    });
+  }
+
+  const status = entryResult.data.status;
+
+  // stale → incompatible, no negotiated version
+  if (status === "stale") {
+    return makeResult({
+      serverVersion: serverCap.version,
+      result: "incompatible",
+      reason: `capability "${capability}" is stale; cannot negotiate a usable version`,
+    });
+  }
+
+  // unknown → unknown immediately, no version comparison
+  if (status === "unknown") {
+    return makeResult({
+      serverVersion: serverCap.version,
+      result: "unknown",
+      reason: `capability "${capability}" status is unknown; cannot determine compatibility`,
+    });
+  }
+
+  if (status === "unsupported") {
+    return makeResult({
+      serverVersion: serverCap.version,
+      reason: `capability "${capability}" is explicitly unsupported`,
+    });
+  }
+
+  // Version comparison for supported/deprecated/experimental
+  const serverParts = parseCapVersion(serverCap.version);
+  if (!serverParts) {
+    return makeResult({
+      serverVersion: serverCap.version,
+      reason: "cannot parse server version numbers",
+    });
+  }
+
+  if (clientParts[1] !== serverParts[1]) {
+    return makeResult({
+      serverVersion: serverCap.version,
+      result: "incompatible",
+      reason: `major version mismatch: client ${clientParts[1]}, server ${serverParts[1]}`,
+    });
+  }
+
+  if (
+    serverParts[2] > clientParts[2] ||
+    (serverParts[2] === clientParts[2] && serverParts[3] >= clientParts[3])
+  ) {
+    const rawResult = {
+      capability,
+      clientVersion,
+      serverVersion: serverCap.version,
+      negotiatedVersion: serverCap.version,
+      tenantScope: requestedTenant,
+      result: clientVersion === serverCap.version ? "matched" : "upgraded",
+    };
+    const parsed = negotiationResultSchema.safeParse(rawResult);
+    if (!parsed.success) {
+      return makeResult({
+        serverVersion: serverCap.version,
+        reason: `output validation failed: ${parsed.error.issues.map((i) => i.message).join("; ")}`,
+      });
+    }
+    return parsed.data;
+  }
+
+  const rawResult = {
+    capability,
+    clientVersion,
+    serverVersion: serverCap.version,
+    negotiatedVersion: serverCap.version,
+    tenantScope: requestedTenant,
+    result: "downgraded",
+    reason: `server version ${serverCap.version} is behind client ${clientVersion}`,
+  };
+  const parsed = negotiationResultSchema.safeParse(rawResult);
+  if (!parsed.success) {
+    return makeResult({
+      serverVersion: serverCap.version,
+      reason: `output validation failed: ${parsed.error.issues.map((i) => i.message).join("; ")}`,
+    });
+  }
+  return parsed.data;
+}

package/src/engram/contracts/content-hash.js

@@ -0,0 +1,8 @@
+/** Structural SHA-256 address only; callers still verify bytes and trust. */
+import { z } from "zod";
+
+// 32 bytes: 64 hexadecimal characters or canonical padded base64.
+export const sha256ContentHashSchema = z.string().regex(
+  /^sha256:(?:[0-9a-fA-F]{64}|[A-Za-z0-9+/]{42}[AEIMQUYcgkosw048]=)$/,
+  { message: "contentHash must be a complete sha256 digest in hex or canonical base64" },
+);

package/src/engram/contracts/evidence.js

@@ -0,0 +1,258 @@
+/**
+ * ENGRAM §EW02 — Evidence contract (R09 truth).
+ *
+ * Every assertion's evidence is addressable. This module codifies:
+ *   - Evidence addresses: stable references to the source of an assertion
+ *   - Pagination: cursor-based evidence list traversal
+ *   - Migration policy: evidence format version compatibility
+ *   - Freshness: every evidence carries an asOf or declares itself stale
+ *
+ * Mandatory constraint (ticket 73ead329): include unknown/unsupported/stale
+ * errors, pagination, evidence addresses, migration policy and protocol
+ * capability negotiation.
+ *
+ * Luna-judge P2: evidencePageSchema requires nextCursor when hasMore is true.
+ */
+
+import { z } from "zod";
+import { EVIDENCE_SCHEMA_VERSION } from "./versions.js";
+import { nonblankIdentitySchema } from "./identity.js";
+
+/**
+ * Supported evidence locator schemes. "screenshot" and
+ * "image" are explicitly banned (ticket 73ead329: no inferred backend
+ * endpoints from screenshots).
+ */
+const TRUSTED_SCHEMES = Object.freeze(["file", "http", "https", "engram", "receipt", "inline"]);
+
+/**
+ * An evidence address: a stable reference to where an assertion's proof lives.
+ * Must NOT be inferred from screenshots (ticket 73ead329 constraint).
+ *
+ * These fields record a provenance claim. Parsing them does not authenticate
+ * the claimed verifier; consumers must check it against a trusted source.
+ */
+export const evidenceAddressSchema = z.object({
+  /** Protocol/scheme: must be an allowed locator scheme */
+  scheme: z.enum(["file", "http", "https", "engram", "receipt", "inline"]),
+  /** Locator within that scheme */
+  locator: z.string().min(1),
+  /** Content hash at the time of reference (for integrity) */
+  contentHash: z.string().min(1).optional(),
+  /** When this evidence was captured */
+  capturedAt: z.string().datetime().optional(),
+  /** Source version that produced this evidence */
+  sourceVersion: nonblankIdentitySchema,
+  /** Tenant scope of the evidence */
+  tenantScope: nonblankIdentitySchema,
+  /** Whether the evidence is still reachable */
+  reachable: z.boolean().optional(),
+  /** Verifier identity — who attested this address was not screenshot-inferred */
+  verifiedBy: z.string().min(1).optional(),
+}).strict().refine(
+  (addr) => {
+    // Require a verifier identity as metadata, but do not treat this string as
+    // proof of independent verification.
+    if (!addr.verifiedBy) return false;
+    return true;
+  },
+  {
+    message: "evidence address must claim verifiedBy; a trusted source must verify the source version and claim",
+    path: ["verifiedBy"],
+  },
+);
+
+/**
+ * An evidence record: the address plus the actual evidence payload.
+ */
+export const evidenceRecordSchema = z.object({
+  address: evidenceAddressSchema,
+  /** The raw evidence payload (type depends on scheme) */
+  payload: z.json(),
+  /** Schema version of the evidence format */
+  schemaVersion: z.literal(EVIDENCE_SCHEMA_VERSION),
+  /** When the evidence was collected */
+  collectedAt: z.string().datetime(),
+  /** When the evidence expires (if applicable) */
+  expiresAt: z.string().datetime().optional(),
+  /** Model confidence in the evidence interpretation */
+  modelConfidence: z.enum(["high", "medium", "low", "unavailable"]).optional(),
+  /** Sender's verification claim; parsing this boolean does not establish trust */
+  independentlyVerified: z.boolean().optional(),
+  /** Claimed verifier identity; authenticate it through a trusted runtime source */
+  verifiedBy: z.string().min(1).optional(),
+}).strict().superRefine((record, ctx) => {
+  if (record.address.capturedAt && Date.parse(record.address.capturedAt) > Date.parse(record.collectedAt)) {
+    ctx.addIssue({ code: "custom", message: "address capturedAt cannot be after collectedAt", path: ["address", "capturedAt"] });
+  }
+  if (record.expiresAt && Date.parse(record.expiresAt) <= Date.parse(record.collectedAt)) {
+    ctx.addIssue({ code: "custom", message: "expiresAt must be after collectedAt", path: ["expiresAt"] });
+  }
+});
+
+/**
+ * Paginated evidence list.
+ *
+ * When hasMore is true, nextCursor is required so clients can retrieve the
+ * next page (luna-judge P2 finding).
+ */
+export const evidencePageSchema = z.object({
+  items: z.array(evidenceRecordSchema),
+  cursor: z.string().optional(),
+  nextCursor: z.string().optional(),
+  hasMore: z.boolean(),
+  total: z.number().int().nonnegative().optional(),
+}).strict().superRefine((data, ctx) => {
+  if (data.hasMore && !data.nextCursor) {
+    ctx.addIssue({ code: "custom", message: "hasMore requires nextCursor for pagination", path: ["nextCursor"] });
+  }
+  const scopes = new Set(data.items.map((record) => record.address.tenantScope));
+  if (scopes.size > 1) {
+    ctx.addIssue({ code: "custom", message: "evidence page cannot mix tenant scopes", path: ["items"] });
+  }
+  if (data.total != null && data.total < data.items.length) {
+    ctx.addIssue({ code: "custom", message: "total cannot be smaller than items count", path: ["total"] });
+  }
+});
+
+/**
+ * Migration policy for evidence format changes.
+ */
+export const evidenceMigrationPolicySchema = z.object({
+  fromSchemaVersion: z.string().min(1),
+  toSchemaVersion: z.string().min(1),
+  compatibility: z.enum(["compatible", "breaking", "additive"]),
+  migrationNotes: z.string().optional(),
+  createdAt: z.string().datetime(),
+  appliesToSchemes: z.array(z.string()).optional(),
+}).strict();
+
+/**
+ * Freshness declaration for an evidence set.
+ */
+export const evidenceFreshnessSchema = z.object({
+  asOf: z.string().datetime(),
+  /** Time at which the stale claim was evaluated; required when isStale is supplied. */
+  evaluatedAt: z.string().datetime().optional(),
+  coverage: z.object({
+    totalAssertions: z.number().int().nonnegative(),
+    evidenced: z.number().int().nonnegative(),
+    ratio: z.number().min(0).max(1),
+  }).strict().superRefine((coverage, ctx) => {
+    if (coverage.evidenced > coverage.totalAssertions) {
+      ctx.addIssue({ code: "custom", path: ["evidenced"], message: "evidenced cannot exceed totalAssertions" });
+    }
+    const expected = coverage.totalAssertions === 0 ? 0 : coverage.evidenced / coverage.totalAssertions;
+    if (Math.abs(coverage.ratio - expected) > 1e-9) {
+      ctx.addIssue({ code: "custom", path: ["ratio"], message: "ratio must match evidenced / totalAssertions" });
+    }
+  }),
+  staleAfterMs: z.number().int().positive().optional(),
+  isStale: z.boolean().optional(),
+}).strict().superRefine((freshness, ctx) => {
+  if (freshness.evaluatedAt && Date.parse(freshness.evaluatedAt) < Date.parse(freshness.asOf)) {
+    ctx.addIssue({ code: "custom", path: ["evaluatedAt"],
+      message: "evaluatedAt cannot precede asOf" });
+    return;
+  }
+  if (freshness.isStale === undefined) return;
+  if (!freshness.evaluatedAt || freshness.staleAfterMs === undefined) {
+    ctx.addIssue({ code: "custom", path: ["isStale"],
+      message: "isStale requires evaluatedAt and staleAfterMs" });
+    return;
+  }
+  const ageMs = Date.parse(freshness.evaluatedAt) - Date.parse(freshness.asOf);
+  if (ageMs < 0 || freshness.isStale !== (ageMs >= freshness.staleAfterMs)) {
+    ctx.addIssue({ code: "custom", path: ["isStale"],
+      message: "isStale must agree with asOf, evaluatedAt and staleAfterMs" });
+  }
+});
+
+/**
+ * Error types for evidence operations.
+ */
+export class EvidenceError extends Error {
+  constructor(message, code, address) {
+    super(message);
+    this.name = "EvidenceError";
+    this.code = code;
+    this.address = address || null;
+  }
+}
+
+export function evidenceNotFound(address) {
+  return new EvidenceError(
+    `evidence at "${address}" not found or unreachable`,
+    "evidence_not_found",
+    address,
+  );
+}
+
+export function evidenceStale(address, asOf) {
+  return new EvidenceError(
+    `evidence at "${address}" is stale (asOf ${asOf})`,
+    "evidence_stale",
+    address,
+  );
+}
+
+export function evidenceUnsupportedScheme(scheme) {
+  return new EvidenceError(
+    `evidence scheme "${scheme}" is not supported by this runtime`,
+    "unsupported_evidence_scheme",
+    null,
+  );
+}
+
+/**
+ * Validate the address shape and ask a trusted, out-of-band source verifier
+ * whether it was actually derived from the stated source. Caller-supplied
+ * sourceVersion, hash, and verifiedBy strings cannot prove this by themselves.
+ *
+ * @param {object} address — evidenceAddressSchema-shaped
+ * @param {{verifySource?: (address: object) => boolean}} options
+ * @returns {{ valid: boolean, error?: string }}
+ */
+export function validateNotScreenshotInferred(address, { verifySource } = {}) {
+  if (!address || typeof address !== "object") {
+    return { valid: false, error: "evidence address is required" };
+  }
+  if (address.scheme === "screenshot" || address.scheme === "image") {
+    return {
+      valid: false,
+      error: `evidence scheme "${address.scheme}" is screenshot-inferred; backend endpoints must not be inferred from screenshots (ticket 73ead329)`,
+    };
+  }
+  if (address.scheme && !TRUSTED_SCHEMES.includes(address.scheme)) {
+    return {
+      valid: false,
+      error: `evidence scheme "${address.scheme}" is not a trusted scheme; must be one of: ${TRUSTED_SCHEMES.join(", ")}`,
+    };
+  }
+  if (!address.sourceVersion && !address.contentHash) {
+    return {
+      valid: false,
+      error: "evidence address lacks both sourceVersion and contentHash; cannot verify it was not screenshot-inferred",
+    };
+  }
+  if (!address.verifiedBy) {
+    return {
+      valid: false,
+      error: "evidence address lacks verifiedBy metadata; trusted source verification is also required",
+    };
+  }
+  if (!evidenceAddressSchema.safeParse(address).success) {
+    return { valid: false, error: "evidence address does not match the required source and tenant shape" };
+  }
+  if (typeof verifySource !== "function") {
+    return { valid: false, error: "trusted source verification is required; verifiedBy is only a claim" };
+  }
+  try {
+    if (verifySource(address) !== true) {
+      return { valid: false, error: "trusted source did not verify this evidence address" };
+    }
+  } catch {
+    return { valid: false, error: "trusted source verification failed" };
+  }
+  return { valid: true };
+}