feat(agent): add graph evidence protocol

.changeset/steady-graphs-prove.md

@@ -0,0 +1,7 @@
+---
+"@sapiom/agent": minor
+---
+
+Add the strict package graph-evidence protocol with deterministic static results,
+idempotent runtime events, endpoint quarantine, lifecycle reference semantics,
+and stable connector conformance helpers.

packages/agent/README.md

@@ -56,6 +56,70 @@ A step declares the transitions it may take (`next` / `terminal` / `canFail` /
 undeclared transition is a compile error. The build reads those same declarations
 to render the orchestration graph without executing anything.
 
+## Package graph evidence
+
+`PackageInventory` answers which agents exist and where they live. The separately
+versioned package graph-evidence protocol answers why two inventory agents are
+connected. Protocol 1 admits four factual relation/basis pairs:
+
+| Relation  | Basis               | Evidence meaning                           |
+| --------- | ------------------- | ------------------------------------------ |
+| `invokes` | `static-invocation` | Source proves one agent starts another     |
+| `invokes` | `runtime-dispatch`  | The engine observed a caller/callee pair   |
+| `feeds`   | `static-dataflow`   | Source provenance reaches another input    |
+| `feeds`   | `runtime-handoff`   | Runtime lineage proves a supported handoff |
+
+Every accepted record names `fromAgentKey` and `toAgentKey` explicitly. Static
+results reuse the exact inventory version and additionally carry an analysis
+fingerprint, producer identity/version, coverage, deterministic diagnostics, and
+quarantine. Runtime evidence is an append-only bundle event keyed by an
+authoritative event ID. Keep one runtime evidence state per immutable bundle and
+start a fresh state when the bundle digest changes; cross-bundle appends conflict
+and leave the existing state unchanged. The helpers expose reference
+replacement/idempotency semantics only; persistence and production graph
+projection remain server concerns.
+
+```ts
+import {
+  createPackageGraphEvidenceStaticResult,
+  type PackageInventory,
+} from "@sapiom/agent";
+
+export function directInvocationEvidence(inventory: PackageInventory) {
+  return createPackageGraphEvidenceStaticResult(
+    {
+      scope: inventory.version,
+      producer: { id: "acme.direct-invocation", version: "1.0.0" },
+      analysisFingerprint:
+        "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+      outcome: "success",
+      coverage: { status: "complete" },
+      candidates: [
+        {
+          fromAgentKey: "coordinator",
+          toAgentKey: "research",
+          relation: "invokes",
+          basis: "static-invocation",
+          mode: "blocking",
+          callsites: [
+            { kind: "source-callsite", ref: "callsite:coordinator.research" },
+          ],
+        },
+      ],
+    },
+    inventory,
+  );
+}
+```
+
+Evidence producers must create opaque handles and keep absolute or relative
+paths, execution IDs, lineage IDs, prompts, reports, inputs, outputs, and tool
+payloads behind an authorized producer-owned resolver. The schema enforces a
+restricted public-safe character set for those handles; it cannot determine
+whether a permitted string contains a sensitive identifier. Graph evidence is
+explanatory metadata only: it cannot change execution, routing, authorization,
+deployment, builds, or billing.
+
 ## The entry input contract
 
 A step's `inputSchema` (a zod schema, imported from `zod/v4`) types and validates that
@@ -176,6 +240,7 @@ Things to know:
     return pauseUntilSignal(run, { resumeStep: "review" });
   }
   ```
+
 - **Outside an agent run nothing changes** — `await launch().wait()` the capability as
   usual; the pause wiring only engages when a step pauses on the handle.
 

packages/agent/src/index.ts

@@ -121,6 +121,42 @@ export type {
   PackageInventoryVersion,
 } from './package-inventory.js';
 
+// Package-scoped relationship evidence — separate from identity inventory.
+export {
+  PACKAGE_GRAPH_EVIDENCE_PROTOCOL,
+  advancePackageGraphStaticEvidenceState,
+  appendPackageGraphRuntimeEvidenceEvent,
+  createPackageGraphEvidenceStaticResult,
+  createPackageGraphRuntimeEvidenceEvent,
+  packageGraphEvidenceStaticResultSchema,
+  packageGraphRuntimeEvidenceEventSchema,
+  projectPackageGraphEvidence,
+} from './package-graph-evidence.js';
+export type {
+  AppendPackageGraphRuntimeEvidenceEventResult,
+  CreatePackageGraphEvidenceStaticResultInput,
+  CreatePackageGraphRuntimeEvidenceEventResult,
+  PackageGraphEvidenceCandidate,
+  PackageGraphEvidenceConnector,
+  PackageGraphEvidenceCoverage,
+  PackageGraphEvidenceCoverageGap,
+  PackageGraphEvidenceDiagnostic,
+  PackageGraphEvidenceDiagnosticCode,
+  PackageGraphEvidenceDigest,
+  PackageGraphEvidenceProducer,
+  PackageGraphEvidenceProjectedSupport,
+  PackageGraphEvidenceProjectionSource,
+  PackageGraphEvidenceQuarantine,
+  PackageGraphEvidenceRecord,
+  PackageGraphEvidenceReferenceProjection,
+  PackageGraphEvidenceStaticResult,
+  PackageGraphRuntimeEvidenceCandidate,
+  PackageGraphRuntimeEvidenceEvent,
+  PackageGraphRuntimeEvidenceState,
+  PackageGraphStaticEvidenceCandidate,
+  PackageGraphStaticEvidenceState,
+} from './package-graph-evidence.js';
+
 // Manifest generator + graph validation — called by the build phase.
 export { buildManifest, validateGraph, assertValidGraph } from './build-manifest.js';
 export type { GraphValidation } from './build-manifest.js';