@kya-os/contracts 1.8.1 → 1.9.1

package/dist/reputation/interactions.js

@@ -0,0 +1,82 @@
+"use strict";
+/**
+ * Interaction Report Request Contract
+ *
+ * The per-tool-call attestation body that identity-aware runtimes POST to
+ * KTA's `POST /api/v1/agents/{did}/interactions` endpoint (xmcp-i#413). KTA
+ * verifies the embedded JWS against the agent's registered public key and
+ * folds the outcome into the Bayesian reputation engine.
+ *
+ * WHY this lives in @kya-os/contracts: per the repo's API-parity rule, the
+ * wire shape of any cross-service POST must be a shared, Zod-validated
+ * contract — never inlined at the call site. The producer here is
+ * `@kya-os/compute`'s attestation reporter; the consumer is the KTA route.
+ *
+ * PARITY CAVEAT: KTA's receiving schema lives in a different repository
+ * (Know-That-Ai/know-that-ai → `src/app/api/v1/agents/[did]/interactions/`)
+ * and cannot be imported or validated from here. This schema mirrors the body
+ * shape already accepted in production (the existing attestation flow), and
+ * MUST be kept in lock-step with that route when either side changes.
+ *
+ * Related Spec: MCP-I §5 (Reputation)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InteractionReportRequestSchema = exports.InteractionContextSchema = exports.InteractionOutcomeSchema = exports.INTERACTION_TYPE_SCOPE_EXECUTED = void 0;
+exports.validateInteractionReportRequest = validateInteractionReportRequest;
+const zod_1 = require("zod");
+/**
+ * Interaction classification. Open-ended on the wire (KTA may accept more
+ * types over time), but the per-tool-call attestation path emits exactly
+ * `"scope_executed"`. Modeled as a string with that documented default rather
+ * than a closed enum so adding a new KTA-side type does not require a
+ * contracts bump on the producer before the receiver is ready.
+ */
+exports.INTERACTION_TYPE_SCOPE_EXECUTED = "scope_executed";
+/**
+ * Coarse success/failure outcome KTA folds into the reputation score. The
+ * compute reporter collapses its finer 4-value status (success/error/denied/
+ * timeout) onto this two-value axis — anything that is not an unambiguous
+ * success counts as a failure for reputation purposes.
+ */
+exports.InteractionOutcomeSchema = zod_1.z.enum(["success", "failure"]);
+/**
+ * Evidentiary context carried alongside the signed attestation. `client_did`
+ * is optional because the agent may receive calls from un-attested clients
+ * during the rollout window; the attestation still has value without it.
+ */
+exports.InteractionContextSchema = zod_1.z.object({
+    /** MCP session id from the originating tools/call. May be empty for headless flows. */
+    session_id: zod_1.z.string(),
+    /** Calling client's DID, when known. Omitted (not null) when un-attested. */
+    client_did: zod_1.z.string().optional(),
+    /** Compact JWS attestation of the tool call, signed by the agent's key. */
+    attestation_jws: zod_1.z.string(),
+});
+/**
+ * Interaction Report Request Schema
+ *
+ * Fire-and-forget body POSTed per tool call. Authenticated by the
+ * `x-api-key` header (not part of the body); idempotency is the caller's
+ * responsibility via `idempotency_key`.
+ */
+exports.InteractionReportRequestSchema = zod_1.z.object({
+    /** Interaction classification — `"scope_executed"` for tool-call attestations. */
+    interaction_type: zod_1.z.string(),
+    /** Reputation-facing outcome. */
+    outcome: exports.InteractionOutcomeSchema,
+    /** Authorized scopes for the call, when a delegation context supplies them. */
+    scopes: zod_1.z.array(zod_1.z.string()).optional(),
+    /** ISO 8601 timestamp of the call, set when the attestation is signed. */
+    timestamp: zod_1.z.string(),
+    /** Evidentiary context including the signed attestation. */
+    context: exports.InteractionContextSchema,
+    /** Per-call key so a retried POST of the same call is deduped by KTA. */
+    idempotency_key: zod_1.z.string(),
+});
+/**
+ * Validate an interaction report request. Mirrors the `validate*` helpers in
+ * `./api.ts` so call sites can branch on `.success` without importing zod.
+ */
+function validateInteractionReportRequest(data) {
+    return exports.InteractionReportRequestSchema.safeParse(data);
+}

package/dist/runtime/headers.d.ts

@@ -13,31 +13,34 @@
  */
 export interface DownstreamHeaders {
     /** DID of the verified agent */
-    'KYA-Agent-DID': string;
-    /** Optional delegation ID */
-    'KYA-Delegation-Id'?: string;
+    'KYA-OS-Agent-DID': string;
     /** Optional delegation chain (format: vc_id>del_id>...) */
-    'KYA-Delegation-Chain'?: string;
+    'KYA-OS-Delegation-Chain'?: string;
+    /** Optional Layer 2 delegation proof (signed JWT) */
+    'KYA-OS-Delegation-Proof'?: string;
+    /** Optional JWS-compact DelegationCredential VC */
+    'KYA-OS-Delegation-Credential'?: string;
     /** Proof ID for audit trail */
     'KYA-Proof-Id': string;
     /** Optional CRISP spend info (JSON string: {unit, delta, remaining}) */
     'KYA-CRISP-Spend'?: string;
     /** Optional session ID */
-    'KYA-Session-Id'?: string;
+    'KYA-OS-Session-Id'?: string;
     /** Optional scopes */
-    'KYA-Granted-Scopes'?: string;
+    'KYA-OS-Granted-Scopes'?: string;
 }
 /**
  * Header names as constants for type safety
  */
 export declare const DOWNSTREAM_HEADER_NAMES: Readonly<{
-    readonly AGENT_DID: "KYA-Agent-DID";
-    readonly DELEGATION_ID: "KYA-Delegation-Id";
-    readonly DELEGATION_CHAIN: "KYA-Delegation-Chain";
+    readonly AGENT_DID: "KYA-OS-Agent-DID";
+    readonly DELEGATION_CHAIN: "KYA-OS-Delegation-Chain";
+    readonly DELEGATION_PROOF: "KYA-OS-Delegation-Proof";
+    readonly DELEGATION_CREDENTIAL: "KYA-OS-Delegation-Credential";
     readonly PROOF_ID: "KYA-Proof-Id";
     readonly CRISP_SPEND: "KYA-CRISP-Spend";
-    readonly SESSION_ID: "KYA-Session-Id";
-    readonly SCOPES: "KYA-Granted-Scopes";
+    readonly SESSION_ID: "KYA-OS-Session-Id";
+    readonly SCOPES: "KYA-OS-Granted-Scopes";
 }>;
 /**
  * CRISP Spend Info
@@ -75,8 +78,9 @@ export declare function parseCrispSpend(headerValue: string): CrispSpendInfo | n
 export declare function createDownstreamHeaders(config: {
     agentDid: string;
     proofId: string;
-    delegationId?: string;
     delegationChain?: string;
+    delegationProof?: string;
+    delegationCredential?: string;
     crispSpend?: CrispSpendInfo;
     sessionId?: string;
     scopes?: string[];

package/dist/runtime/headers.js

@@ -16,13 +16,14 @@ exports.createDownstreamHeaders = createDownstreamHeaders;
  * Header names as constants for type safety
  */
 exports.DOWNSTREAM_HEADER_NAMES = Object.freeze({
-    AGENT_DID: 'KYA-Agent-DID',
-    DELEGATION_ID: 'KYA-Delegation-Id',
-    DELEGATION_CHAIN: 'KYA-Delegation-Chain',
+    AGENT_DID: 'KYA-OS-Agent-DID',
+    DELEGATION_CHAIN: 'KYA-OS-Delegation-Chain',
+    DELEGATION_PROOF: 'KYA-OS-Delegation-Proof',
+    DELEGATION_CREDENTIAL: 'KYA-OS-Delegation-Credential',
     PROOF_ID: 'KYA-Proof-Id',
     CRISP_SPEND: 'KYA-CRISP-Spend',
-    SESSION_ID: 'KYA-Session-Id',
-    SCOPES: 'KYA-Granted-Scopes',
+    SESSION_ID: 'KYA-OS-Session-Id',
+    SCOPES: 'KYA-OS-Granted-Scopes',
 });
 /**
  * Helper to serialize CRISP spend info to header value
@@ -59,23 +60,26 @@ function parseCrispSpend(headerValue) {
  */
 function createDownstreamHeaders(config) {
     const headers = {
-        'KYA-Agent-DID': config.agentDid,
+        'KYA-OS-Agent-DID': config.agentDid,
         'KYA-Proof-Id': config.proofId,
     };
-    if (config.delegationId) {
-        headers['KYA-Delegation-Id'] = config.delegationId;
-    }
     if (config.delegationChain) {
-        headers['KYA-Delegation-Chain'] = config.delegationChain;
+        headers['KYA-OS-Delegation-Chain'] = config.delegationChain;
+    }
+    if (config.delegationProof) {
+        headers['KYA-OS-Delegation-Proof'] = config.delegationProof;
+    }
+    if (config.delegationCredential) {
+        headers['KYA-OS-Delegation-Credential'] = config.delegationCredential;
     }
     if (config.crispSpend) {
         headers['KYA-CRISP-Spend'] = serializeCrispSpend(config.crispSpend);
     }
     if (config.sessionId) {
-        headers['KYA-Session-Id'] = config.sessionId;
+        headers['KYA-OS-Session-Id'] = config.sessionId;
     }
     if (config.scopes && config.scopes.length > 0) {
-        headers['KYA-Granted-Scopes'] = config.scopes.join(',');
+        headers['KYA-OS-Granted-Scopes'] = config.scopes.join(',');
     }
     return headers;
 }

package/dist/verifier.d.ts

@@ -9,6 +9,7 @@ export declare const AgentContextSchema: z.ZodObject<{
     scopes: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
     session: z.ZodString;
     confidence: z.ZodLiteral<"verified">;
+    outcome: z.ZodOptional<z.ZodEnum<["allowed", "denied", "step_up_required", "needs_authorization"]>>;
     delegationRef: z.ZodOptional<z.ZodString>;
     registry: z.ZodString;
     verifiedAt: z.ZodNumber;
@@ -22,6 +23,7 @@ export declare const AgentContextSchema: z.ZodObject<{
     verifiedAt: number;
     subject?: string | undefined;
     delegationRef?: string | undefined;
+    outcome?: "allowed" | "denied" | "step_up_required" | "needs_authorization" | undefined;
 }, {
     did: string;
     kid: string;
@@ -32,6 +34,7 @@ export declare const AgentContextSchema: z.ZodObject<{
     scopes?: string[] | undefined;
     subject?: string | undefined;
     delegationRef?: string | undefined;
+    outcome?: "allowed" | "denied" | "step_up_required" | "needs_authorization" | undefined;
 }>;
 export declare const VerifierResultSchema: z.ZodObject<{
     success: z.ZodBoolean;
@@ -43,6 +46,7 @@ export declare const VerifierResultSchema: z.ZodObject<{
         scopes: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
         session: z.ZodString;
         confidence: z.ZodLiteral<"verified">;
+        outcome: z.ZodOptional<z.ZodEnum<["allowed", "denied", "step_up_required", "needs_authorization"]>>;
         delegationRef: z.ZodOptional<z.ZodString>;
         registry: z.ZodString;
         verifiedAt: z.ZodNumber;
@@ -56,6 +60,7 @@ export declare const VerifierResultSchema: z.ZodObject<{
         verifiedAt: number;
         subject?: string | undefined;
         delegationRef?: string | undefined;
+        outcome?: "allowed" | "denied" | "step_up_required" | "needs_authorization" | undefined;
     }, {
         did: string;
         kid: string;
@@ -66,6 +71,7 @@ export declare const VerifierResultSchema: z.ZodObject<{
         scopes?: string[] | undefined;
         subject?: string | undefined;
         delegationRef?: string | undefined;
+        outcome?: "allowed" | "denied" | "step_up_required" | "needs_authorization" | undefined;
     }>>;
     error: z.ZodOptional<z.ZodObject<{
         code: z.ZodString;
@@ -102,6 +108,7 @@ export declare const VerifierResultSchema: z.ZodObject<{
         verifiedAt: number;
         subject?: string | undefined;
         delegationRef?: string | undefined;
+        outcome?: "allowed" | "denied" | "step_up_required" | "needs_authorization" | undefined;
     } | undefined;
 }, {
     success: boolean;
@@ -122,6 +129,7 @@ export declare const VerifierResultSchema: z.ZodObject<{
         scopes?: string[] | undefined;
         subject?: string | undefined;
         delegationRef?: string | undefined;
+        outcome?: "allowed" | "denied" | "step_up_required" | "needs_authorization" | undefined;
     } | undefined;
 }>;
 export declare const StructuredErrorSchema: z.ZodObject<{
@@ -169,15 +177,16 @@ export type AgentContext = z.infer<typeof AgentContextSchema>;
 export type VerifierResult = z.infer<typeof VerifierResultSchema>;
 export type StructuredError = z.infer<typeof StructuredErrorSchema>;
 export declare const AGENT_HEADERS: {
-    readonly DID: "KYA-Agent-DID";
-    readonly KEY_ID: "KYA-Agent-KeyId";
-    readonly SUBJECT: "KYA-Agent-Subject";
-    readonly SCOPES: "KYA-Agent-Scopes";
-    readonly SESSION: "KYA-Agent-Session";
-    readonly CONFIDENCE: "KYA-Agent-Confidence";
-    readonly DELEGATION_REF: "KYA-Delegation-Ref";
-    readonly REGISTRY: "KYA-Agent-Registry";
-    readonly VERIFIED_AT: "KYA-Verified-At";
+    readonly DID: "KYA-OS-Agent-DID";
+    readonly KEY_ID: "KYA-OS-Agent-KeyId";
+    readonly SUBJECT: "KYA-OS-Agent-Subject";
+    readonly SCOPES: "KYA-OS-Agent-Scopes";
+    readonly SESSION: "KYA-OS-Agent-Session";
+    readonly CONFIDENCE: "KYA-OS-Agent-Confidence";
+    readonly OUTCOME: "KYA-OS-Agent-Outcome";
+    readonly DELEGATION_REF: "KYA-OS-Delegation-Ref";
+    readonly REGISTRY: "KYA-OS-Agent-Registry";
+    readonly VERIFIED_AT: "KYA-OS-Verified-At";
 };
 export declare const VERIFIER_ERROR_CODES: {
     readonly PROOF_INVALID_TS: "XMCP_I_PROOF_INVALID_TS";
@@ -186,6 +195,7 @@ export declare const VERIFIER_ERROR_CODES: {
     readonly PROOF_SKEW_EXCEEDED: "XMCP_I_PROOF_SKEW_EXCEEDED";
     readonly SESSION_IDLE_EXPIRED: "XMCP_I_SESSION_IDLE_EXPIRED";
     readonly SERVER_TIME_INVALID: "XMCP_I_SERVER_TIME_INVALID";
+    readonly OUTCOME_NOT_ALLOWED: "XMCP_I_OUTCOME_NOT_ALLOWED";
 };
 export declare const ERROR_HTTP_STATUS: {
     readonly XMCP_I_EBADPROOF: 403;
@@ -202,4 +212,5 @@ export declare const ERROR_HTTP_STATUS: {
     readonly XMCP_I_PROOF_SKEW_EXCEEDED: 401;
     readonly XMCP_I_SESSION_IDLE_EXPIRED: 401;
     readonly XMCP_I_SERVER_TIME_INVALID: 500;
+    readonly XMCP_I_OUTCOME_NOT_ALLOWED: 403;
 };

package/dist/verifier.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ERROR_HTTP_STATUS = exports.VERIFIER_ERROR_CODES = exports.AGENT_HEADERS = exports.StructuredErrorSchema = exports.VerifierResultSchema = exports.AgentContextSchema = void 0;
 const zod_1 = require("zod");
+const proof_js_1 = require("./proof.js");
 /**
  * Verifier middleware schemas and headers
  */
@@ -12,6 +13,13 @@ exports.AgentContextSchema = zod_1.z.object({
     scopes: zod_1.z.array(zod_1.z.string()).default([]),
     session: zod_1.z.string().min(1),
     confidence: zod_1.z.literal("verified"),
+    // Policy outcome the verified proof attests to (ratified DIF decision).
+    // `confidence: "verified"` means the proof is authentic; `outcome` is the
+    // separate authorization dimension. A PEP must gate on `outcome === "allowed"`
+    // — a verified `denied` / `step_up_required` / `needs_authorization` proof is
+    // authentic but does NOT authorize the call. Optional for backward
+    // compatibility; the verifier always populates it (legacy proofs → "allowed").
+    outcome: proof_js_1.ProofOutcomeSchema.optional(),
     delegationRef: zod_1.z.string().optional(),
     registry: zod_1.z.string().url(),
     verifiedAt: zod_1.z.number().int().positive(),
@@ -44,15 +52,16 @@ exports.StructuredErrorSchema = zod_1.z.object({
 });
 // Header constants (frozen names)
 exports.AGENT_HEADERS = {
-    DID: "KYA-Agent-DID",
-    KEY_ID: "KYA-Agent-KeyId",
-    SUBJECT: "KYA-Agent-Subject",
-    SCOPES: "KYA-Agent-Scopes",
-    SESSION: "KYA-Agent-Session",
-    CONFIDENCE: "KYA-Agent-Confidence",
-    DELEGATION_REF: "KYA-Delegation-Ref",
-    REGISTRY: "KYA-Agent-Registry",
-    VERIFIED_AT: "KYA-Verified-At",
+    DID: "KYA-OS-Agent-DID",
+    KEY_ID: "KYA-OS-Agent-KeyId",
+    SUBJECT: "KYA-OS-Agent-Subject",
+    SCOPES: "KYA-OS-Agent-Scopes",
+    SESSION: "KYA-OS-Agent-Session",
+    CONFIDENCE: "KYA-OS-Agent-Confidence",
+    OUTCOME: "KYA-OS-Agent-Outcome",
+    DELEGATION_REF: "KYA-OS-Delegation-Ref",
+    REGISTRY: "KYA-OS-Agent-Registry",
+    VERIFIED_AT: "KYA-OS-Verified-At",
 };
 // Verifier-specific error codes
 exports.VERIFIER_ERROR_CODES = {
@@ -62,6 +71,7 @@ exports.VERIFIER_ERROR_CODES = {
     PROOF_SKEW_EXCEEDED: "XMCP_I_PROOF_SKEW_EXCEEDED",
     SESSION_IDLE_EXPIRED: "XMCP_I_SESSION_IDLE_EXPIRED",
     SERVER_TIME_INVALID: "XMCP_I_SERVER_TIME_INVALID",
+    OUTCOME_NOT_ALLOWED: "XMCP_I_OUTCOME_NOT_ALLOWED",
 };
 // HTTP status mappings
 exports.ERROR_HTTP_STATUS = {
@@ -80,4 +90,5 @@ exports.ERROR_HTTP_STATUS = {
     [exports.VERIFIER_ERROR_CODES.PROOF_SKEW_EXCEEDED]: 401,
     [exports.VERIFIER_ERROR_CODES.SESSION_IDLE_EXPIRED]: 401,
     [exports.VERIFIER_ERROR_CODES.SERVER_TIME_INVALID]: 500,
+    [exports.VERIFIER_ERROR_CODES.OUTCOME_NOT_ALLOWED]: 403,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kya-os/contracts",
-  "version": "1.8.1",
+  "version": "1.9.1",
   "description": "Shared contracts, types, and schemas for MCP-I framework",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -142,6 +142,7 @@
   },
   "files": [
     "dist",
+    "parity-vectors",
     "package.json",
     "README.md"
   ],

package/parity-vectors/delegation-conformance.json

@@ -0,0 +1,265 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "name": "Delegation chain conformance vectors",
+  "description": "Cascading-revocation, chain-integrity, per-hop attenuation, and multi-hop delegation chains (E3.5 / issue #2904). `core` = full reference semantics (mcp-i-core cascading-revocation + delegation-graph, contracts areChildConstraintsValid). `edge` = reduced-profile kya-os-engine verdict: single-hop is evaluated; multi-hop fails closed to Block(PolicyDenied) unless a higher-priority reason (Revoked/Expired) fires first.",
+  "version": "1.0.0",
+  "vectors": [
+    {
+      "id": "cascade-revoke-ancestor-revokes-leaf",
+      "category": "cascading-revocation",
+      "profiles": ["core", "edge"],
+      "description": "Two-hop chain whose root delegation is revoked while the leaf's own credential is clean. Core: leaf invalid via ancestor cascade. Edge: the engine sees only the leaf's top-level credentialStatus (clean) and cannot observe the ancestor revocation, so it fails closed on the multi-hop chain (PolicyDenied) rather than over-permitting.",
+      "input": {
+        "chain": [
+          {
+            "id": "cr-root",
+            "parentId": null,
+            "issuerDid": "did:web:org.example",
+            "subjectDid": "did:web:agent.example",
+            "grantedScopes": ["read:*"],
+            "credentialStatusId": "https://status.example/revocation/v1#5"
+          },
+          {
+            "id": "cr-leaf",
+            "parentId": "cr-root",
+            "issuerDid": "did:web:agent.example",
+            "subjectDid": "did:key:zSubLeaf",
+            "grantedScopes": ["read:email"],
+            "credentialStatusId": "https://status.example/revocation/v1#9"
+          }
+        ],
+        "requestedScope": "read:email",
+        "revokedStatusIds": ["https://status.example/revocation/v1#5"],
+        "currentTime": 1735689600
+      },
+      "expected": {
+        "core": {
+          "valid": false,
+          "failureReason": "cascaded-revocation",
+          "revokedAncestor": "cr-root"
+        },
+        "edge": {
+          "mode": "fail-closed",
+          "decision": {
+            "kind": "Block",
+            "reason": {
+              "kind": "PolicyDenied",
+              "detail": "multi-hop delegation chain (len=2) not evaluated by reduced edge profile; Layer-2 policy authoritative"
+            }
+          }
+        }
+      },
+      "note": "The leaf's own credentialStatus (#9) is NOT revoked, so the engine's Stage 3 does not fire Block(Revoked); the multi-hop guard yields PolicyDenied. If the leaf's own status WERE revoked, Stage 3's Revoked (priority 0) would outrank PolicyDenied — covered by the cross-runtime matrix, not here."
+    },
+    {
+      "id": "chain-integrity-broken-issuer-linkage",
+      "category": "chain-integrity",
+      "profiles": ["core", "edge"],
+      "description": "Two-hop chain where the leaf's issuer is NOT the root's subject (forged intermediate). Core: invalid-chain via delegation-graph linkage check. Edge: fails closed on the multi-hop chain.",
+      "input": {
+        "chain": [
+          {
+            "id": "ci-root",
+            "parentId": null,
+            "issuerDid": "did:web:org.example",
+            "subjectDid": "did:web:agent.example",
+            "grantedScopes": ["read:*"]
+          },
+          {
+            "id": "ci-leaf",
+            "parentId": "ci-root",
+            "issuerDid": "did:web:evil.example",
+            "subjectDid": "did:key:zSubLeaf",
+            "grantedScopes": ["read:email"]
+          }
+        ],
+        "requestedScope": "read:email",
+        "currentTime": 1735689600
+      },
+      "expected": {
+        "core": {
+          "valid": false,
+          "failureReason": "invalid-chain"
+        },
+        "edge": {
+          "mode": "fail-closed",
+          "decision": {
+            "kind": "Block",
+            "reason": {
+              "kind": "PolicyDenied",
+              "detail": "multi-hop delegation chain (len=2) not evaluated by reduced edge profile; Layer-2 policy authoritative"
+            }
+          }
+        }
+      },
+      "note": "delegation-graph.validateChain requires child.issuerDid === parent.subjectDid (delegation-graph.ts:243). did:web:evil.example breaks the linkage. The flat engine carries no per-hop issuer/subject, so it cannot detect this — fail-closed is the safe reduced-profile behavior."
+    },
+    {
+      "id": "attenuation-child-exceeds-parent-scope",
+      "category": "per-hop-attenuation",
+      "profiles": ["core", "edge"],
+      "description": "Two-hop chain where the child grants MORE than the parent (parent read:* via prefix, child write:billing). Core: attenuation-violation via areChildConstraintsValid. Edge: fails closed. This is the canonical over-permit case the reduced profile closes.",
+      "input": {
+        "chain": [
+          {
+            "id": "at-root",
+            "parentId": null,
+            "issuerDid": "did:web:org.example",
+            "subjectDid": "did:web:agent.example",
+            "grantedScopes": ["read:*"],
+            "constraints": {
+              "crisp": {
+                "scopes": [{ "resource": "read:", "matcher": "prefix" }]
+              }
+            }
+          },
+          {
+            "id": "at-leaf",
+            "parentId": "at-root",
+            "issuerDid": "did:web:agent.example",
+            "subjectDid": "did:key:zSubLeaf",
+            "grantedScopes": ["write:billing"],
+            "constraints": {
+              "crisp": {
+                "scopes": [{ "resource": "write:billing", "matcher": "exact" }]
+              }
+            }
+          }
+        ],
+        "requestedScope": "write:billing",
+        "currentTime": 1735689600
+      },
+      "expected": {
+        "core": {
+          "valid": false,
+          "failureReason": "attenuation-violation"
+        },
+        "edge": {
+          "mode": "fail-closed",
+          "decision": {
+            "kind": "Block",
+            "reason": {
+              "kind": "PolicyDenied",
+              "detail": "multi-hop delegation chain (len=2) not evaluated by reduced edge profile; Layer-2 policy authoritative"
+            }
+          }
+        }
+      },
+      "note": "Today the flat engine would flatten grants to [read:*, write:billing] and scope_satisfies('write:billing', ...) === true → silent Permit. areChildConstraintsValid rejects the widening (write:billing does not start with read:). Fail-closed converts the silent over-permit into Block(PolicyDenied)."
+    },
+    {
+      "id": "multihop-valid-chain-still-fail-closed",
+      "category": "multi-hop-valid",
+      "profiles": ["core", "edge"],
+      "description": "A WELL-FORMED two-hop chain: valid linkage, no revocation, child scopes within parent, request within leaf grant. Core: valid. Edge: STILL fails closed — the reduced profile does not certify multi-hop even when the chain is valid; the over-permit risk is structural, not data-dependent.",
+      "input": {
+        "chain": [
+          {
+            "id": "hp-root",
+            "parentId": null,
+            "issuerDid": "did:web:org.example",
+            "subjectDid": "did:web:agent.example",
+            "grantedScopes": ["read:email"],
+            "credentialStatusId": "https://status.example/revocation/v1#20",
+            "constraints": {
+              "crisp": {
+                "scopes": [{ "resource": "read:email", "matcher": "exact" }]
+              }
+            }
+          },
+          {
+            "id": "hp-leaf",
+            "parentId": "hp-root",
+            "issuerDid": "did:web:agent.example",
+            "subjectDid": "did:key:zSubLeaf",
+            "grantedScopes": ["read:email"],
+            "credentialStatusId": "https://status.example/revocation/v1#21",
+            "constraints": {
+              "crisp": {
+                "scopes": [{ "resource": "read:email", "matcher": "exact" }]
+              }
+            }
+          }
+        ],
+        "requestedScope": "read:email",
+        "revokedStatusIds": [],
+        "currentTime": 1735689600
+      },
+      "expected": {
+        "core": {
+          "valid": true
+        },
+        "edge": {
+          "mode": "fail-closed",
+          "decision": {
+            "kind": "Block",
+            "reason": {
+              "kind": "PolicyDenied",
+              "detail": "multi-hop delegation chain (len=2) not evaluated by reduced edge profile; Layer-2 policy authoritative"
+            }
+          }
+        }
+      },
+      "note": "Deliberate negative-of-convenience: proves the edge profile fails closed even on a VALID multi-hop chain. This is the honest cost of the reduced profile — Layer-2 tenant policy must opt these back in. Prevents a future maintainer from 'optimizing' the guard to permit valid-looking chains."
+    },
+    {
+      "id": "singlehop-scope-permit",
+      "category": "scope-match",
+      "profiles": ["edge"],
+      "description": "Single-hop delegation whose granted scope covers the requested scope. Edge: evaluated → Permit (regression guard that the multi-hop guard does NOT change the len<=1 path).",
+      "input": {
+        "chain": [
+          {
+            "id": "sh-permit",
+            "parentId": null,
+            "issuerDid": "did:web:org.example",
+            "subjectDid": "did:web:agent.example",
+            "grantedScopes": ["read:email"]
+          }
+        ],
+        "requestedScope": "read:email",
+        "currentTime": 1735689600
+      },
+      "expected": {
+        "edge": {
+          "mode": "evaluated",
+          "decision": { "kind": "Permit" }
+        }
+      },
+      "note": "Single-hop is within the engine's competence: it flattens the one step's grants and matches requestedScope. No core counterpart — for single-hop scope the engine is the reference."
+    },
+    {
+      "id": "singlehop-scope-out-of-scope",
+      "category": "scope-match",
+      "profiles": ["edge"],
+      "description": "Single-hop delegation whose granted scope does NOT cover the requested scope. Edge: evaluated → Block(OutOfScope). Proves the guard leaves the genuine single-hop scope rejection intact.",
+      "input": {
+        "chain": [
+          {
+            "id": "sh-oos",
+            "parentId": null,
+            "issuerDid": "did:web:org.example",
+            "subjectDid": "did:web:agent.example",
+            "grantedScopes": ["read:email"]
+          }
+        ],
+        "requestedScope": "write:billing",
+        "currentTime": 1735689600
+      },
+      "expected": {
+        "edge": {
+          "mode": "evaluated",
+          "decision": {
+            "kind": "Block",
+            "reason": {
+              "kind": "OutOfScope",
+              "requested": "write:billing",
+              "granted": ["read:email"]
+            }
+          }
+        }
+      },
+      "note": "Single-hop OutOfScope stays a genuine evaluated rejection (not fail-closed). granted is the flattened single-step grant set."
+    }
+  ]
+}