@redditech/agent-protocol 0.0.0-stage → 0.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +89 -0
- package/LICENSE +21 -0
- package/README.md +394 -2
- package/dist/adl.d.ts +141 -0
- package/dist/adl.js +3601 -0
- package/dist/agent-stack-fixtures.d.ts +743 -0
- package/dist/agent-stack-fixtures.js +1554 -0
- package/dist/ai-catalog.d.ts +128 -0
- package/dist/ai-catalog.js +373 -0
- package/dist/attestation-reputation.d.ts +102 -0
- package/dist/attestation-reputation.js +279 -0
- package/dist/audd-rail-config.d.ts +102 -0
- package/dist/audd-rail-config.js +294 -0
- package/dist/browser-wallet-approval.d.ts +293 -0
- package/dist/browser-wallet-approval.js +1201 -0
- package/dist/discovery-source.d.ts +115 -0
- package/dist/discovery-source.js +251 -0
- package/dist/evidence-archive.d.ts +73 -0
- package/dist/evidence-archive.js +238 -0
- package/dist/index.d.ts +23 -0
- package/dist/index.js +23 -0
- package/dist/mpp-tempo-receipt-shapes.d.ts +201 -0
- package/dist/mpp-tempo-receipt-shapes.js +330 -0
- package/dist/okf-adapter.d.ts +229 -0
- package/dist/okf-adapter.js +556 -0
- package/dist/okf-conformance.d.ts +208 -0
- package/dist/okf-conformance.js +651 -0
- package/dist/okf-instruction-safety.d.ts +192 -0
- package/dist/okf-instruction-safety.js +509 -0
- package/dist/onboarding-analyser-handoff.d.ts +391 -0
- package/dist/onboarding-analyser-handoff.js +959 -0
- package/dist/onboarding-state-machine.d.ts +228 -0
- package/dist/onboarding-state-machine.js +432 -0
- package/dist/payment-records.d.ts +181 -0
- package/dist/payment-records.js +599 -0
- package/dist/policy.d.ts +33 -0
- package/dist/policy.js +45 -0
- package/dist/provider-trust.d.ts +113 -0
- package/dist/provider-trust.js +346 -0
- package/dist/quasar-registry-compatibility.d.ts +113 -0
- package/dist/quasar-registry-compatibility.js +214 -0
- package/dist/ranking-explainability.d.ts +202 -0
- package/dist/ranking-explainability.js +302 -0
- package/dist/receipt-v2.d.ts +202 -0
- package/dist/receipt-v2.js +418 -0
- package/dist/repo-explorer-evidence-manifest.d.ts +387 -0
- package/dist/repo-explorer-evidence-manifest.js +1187 -0
- package/dist/source-diagnostics.d.ts +84 -0
- package/dist/source-diagnostics.js +193 -0
- package/dist/source-trust-conformance-matrix.d.ts +207 -0
- package/dist/source-trust-conformance-matrix.js +672 -0
- package/examples/ard-no-spend-ai-catalog.json +51 -0
- package/examples/ard-no-spend-demo.mjs +355 -0
- package/examples/interpretation-guide-scenarios.mjs +302 -0
- package/package.json +144 -4
|
@@ -0,0 +1,214 @@
|
|
|
1
|
+
export const QUASAR_REGISTRY_COMPATIBILITY_SCHEMA_VERSION = 'reddi.quasar-registry-compatibility.v1';
|
|
2
|
+
const U64_MAX = 18446744073709551615n;
|
|
3
|
+
const BASE58_ALPHABET = '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz';
|
|
4
|
+
export const QUASAR_AGENT_ACCOUNT_COMPATIBILITY = {
|
|
5
|
+
discriminator: [20],
|
|
6
|
+
dataSize: 153,
|
|
7
|
+
pdaSeed: 'agent',
|
|
8
|
+
modelMaxBytes: 64,
|
|
9
|
+
onchainFieldNames: [
|
|
10
|
+
'owner',
|
|
11
|
+
'agentType',
|
|
12
|
+
'model',
|
|
13
|
+
'rateLamports',
|
|
14
|
+
'minReputation',
|
|
15
|
+
'active',
|
|
16
|
+
'reputationScore',
|
|
17
|
+
'jobsCompleted',
|
|
18
|
+
'jobsFailed',
|
|
19
|
+
'createdAt',
|
|
20
|
+
'attestationAccuracy',
|
|
21
|
+
],
|
|
22
|
+
offchainFieldNames: [
|
|
23
|
+
'profileId',
|
|
24
|
+
'listingId',
|
|
25
|
+
'displayName',
|
|
26
|
+
'summary',
|
|
27
|
+
'description',
|
|
28
|
+
'buyerPreview',
|
|
29
|
+
'endpoint',
|
|
30
|
+
'ardUrl',
|
|
31
|
+
'catalogRefs',
|
|
32
|
+
'sourceRefs',
|
|
33
|
+
'authRequirements',
|
|
34
|
+
'auddTerms',
|
|
35
|
+
'evidenceRefs',
|
|
36
|
+
'receiptRefs',
|
|
37
|
+
'trustBadges',
|
|
38
|
+
'providerTrustStatus',
|
|
39
|
+
'capabilities',
|
|
40
|
+
'tags',
|
|
41
|
+
'groups',
|
|
42
|
+
'riskDiagnostics',
|
|
43
|
+
'reviewStates',
|
|
44
|
+
'operatorApprovalEvidenceRef',
|
|
45
|
+
],
|
|
46
|
+
};
|
|
47
|
+
export function deriveQuasarRegistryCompatibility(input) {
|
|
48
|
+
const registrationIntent = input.registrationIntent ?? 'metadata_only';
|
|
49
|
+
const model = input.model ?? fallbackModel(input);
|
|
50
|
+
const onchain = {
|
|
51
|
+
owner: input.owner,
|
|
52
|
+
agentType: deriveAgentType(input.role),
|
|
53
|
+
model,
|
|
54
|
+
rateLamports: input.nativeSolRateLamports === undefined ? undefined : toUnsignedIntegerString(input.nativeSolRateLamports),
|
|
55
|
+
minReputation: input.minReputation ?? 0,
|
|
56
|
+
active: registrationIntent === 'metadata_only' ? false : input.active === true,
|
|
57
|
+
aggregates: normalizeAggregates(input.decodedAggregates),
|
|
58
|
+
};
|
|
59
|
+
const blockedReasons = blockedReasonsFor(input, onchain, registrationIntent);
|
|
60
|
+
const registrationStatus = blockedReasons.length > 0
|
|
61
|
+
? 'blocked'
|
|
62
|
+
: registrationIntent === 'metadata_only'
|
|
63
|
+
? 'metadata_only'
|
|
64
|
+
: 'registerable';
|
|
65
|
+
return {
|
|
66
|
+
schemaVersion: QUASAR_REGISTRY_COMPATIBILITY_SCHEMA_VERSION,
|
|
67
|
+
profileId: input.profileId,
|
|
68
|
+
listingId: input.listingId,
|
|
69
|
+
registrationStatus,
|
|
70
|
+
account: QUASAR_AGENT_ACCOUNT_COMPATIBILITY,
|
|
71
|
+
onchain,
|
|
72
|
+
offchain: {
|
|
73
|
+
...input.offchain,
|
|
74
|
+
profileId: input.profileId,
|
|
75
|
+
listingId: input.listingId,
|
|
76
|
+
displayName: input.displayName,
|
|
77
|
+
summary: input.summary,
|
|
78
|
+
description: input.description,
|
|
79
|
+
catalogRefs: input.offchain.catalogRefs ?? [],
|
|
80
|
+
sourceRefs: input.offchain.sourceRefs ?? [],
|
|
81
|
+
authRequirements: input.offchain.authRequirements ?? [],
|
|
82
|
+
evidenceRefs: input.offchain.evidenceRefs ?? [],
|
|
83
|
+
receiptRefs: input.offchain.receiptRefs ?? [],
|
|
84
|
+
trustBadges: input.offchain.trustBadges ?? [],
|
|
85
|
+
capabilities: input.offchain.capabilities ?? [],
|
|
86
|
+
tags: input.offchain.tags ?? [],
|
|
87
|
+
groups: input.offchain.groups ?? [],
|
|
88
|
+
riskDiagnostics: input.offchain.riskDiagnostics ?? [],
|
|
89
|
+
reviewStates: input.offchain.reviewStates ?? [],
|
|
90
|
+
},
|
|
91
|
+
blockedReasons,
|
|
92
|
+
reasonCodes: reasonCodesFor(input, registrationStatus),
|
|
93
|
+
guardrails: {
|
|
94
|
+
richMetadataOnchain: false,
|
|
95
|
+
auddCustodyOnchain: false,
|
|
96
|
+
endpointOnchain: false,
|
|
97
|
+
evidencePayloadOnchain: false,
|
|
98
|
+
trustBadgeOnchain: false,
|
|
99
|
+
instructionBuilt: false,
|
|
100
|
+
walletSigning: false,
|
|
101
|
+
rpcCall: false,
|
|
102
|
+
programDeploy: false,
|
|
103
|
+
livePaymentExecuted: false,
|
|
104
|
+
},
|
|
105
|
+
};
|
|
106
|
+
}
|
|
107
|
+
function deriveAgentType(role) {
|
|
108
|
+
if (role?.callable && role.attestation)
|
|
109
|
+
return 'Both';
|
|
110
|
+
if (role?.attestation)
|
|
111
|
+
return 'Attestation';
|
|
112
|
+
return 'Primary';
|
|
113
|
+
}
|
|
114
|
+
function fallbackModel(input) {
|
|
115
|
+
const source = input.displayName || input.listingId || 'static-fixture';
|
|
116
|
+
const compact = source.toLowerCase().replace(/[^a-z0-9:_-]+/g, '-').replace(/^-+|-+$/g, '');
|
|
117
|
+
return compact.slice(0, QUASAR_AGENT_ACCOUNT_COMPATIBILITY.modelMaxBytes) || 'static-fixture';
|
|
118
|
+
}
|
|
119
|
+
function normalizeAggregates(input) {
|
|
120
|
+
if (!input)
|
|
121
|
+
return { source: 'not_available' };
|
|
122
|
+
return {
|
|
123
|
+
source: 'decoded_quasar_account',
|
|
124
|
+
reputationScore: input.reputationScore,
|
|
125
|
+
jobsCompleted: input.jobsCompleted === undefined ? undefined : toUnsignedIntegerString(input.jobsCompleted),
|
|
126
|
+
jobsFailed: input.jobsFailed === undefined ? undefined : toUnsignedIntegerString(input.jobsFailed),
|
|
127
|
+
createdAt: input.createdAt === undefined ? undefined : toSignedIntegerString(input.createdAt),
|
|
128
|
+
attestationAccuracy: input.attestationAccuracy,
|
|
129
|
+
};
|
|
130
|
+
}
|
|
131
|
+
function blockedReasonsFor(input, onchain, registrationIntent) {
|
|
132
|
+
const reasons = [
|
|
133
|
+
isNonEmptyString(input.listingId) ? undefined : 'missing_listing_id',
|
|
134
|
+
utf8ByteLength(onchain.model) <= QUASAR_AGENT_ACCOUNT_COMPATIBILITY.modelMaxBytes ? undefined : 'model_too_long_for_quasar_account',
|
|
135
|
+
isUint8(onchain.minReputation) ? undefined : 'invalid_min_reputation',
|
|
136
|
+
onchain.aggregates.reputationScore === undefined || isBasisPointLike(onchain.aggregates.reputationScore) ? undefined : 'invalid_reputation_score',
|
|
137
|
+
onchain.aggregates.attestationAccuracy === undefined || isBasisPointLike(onchain.aggregates.attestationAccuracy) ? undefined : 'invalid_attestation_accuracy',
|
|
138
|
+
registrationIntent === 'metadata_only' || isSolanaPublicKey(input.owner) ? undefined : 'missing_or_invalid_owner',
|
|
139
|
+
registrationIntent === 'metadata_only' || isU64String(onchain.rateLamports) ? undefined : 'missing_native_sol_rate_lamports',
|
|
140
|
+
isNonEmptyString(input.displayName) ? undefined : 'missing_display_name',
|
|
141
|
+
];
|
|
142
|
+
return reasons.filter(isNonEmptyString);
|
|
143
|
+
}
|
|
144
|
+
function reasonCodesFor(input, registrationStatus) {
|
|
145
|
+
const reasonCodes = [
|
|
146
|
+
registrationStatus,
|
|
147
|
+
'rich_metadata_offchain',
|
|
148
|
+
'audd_terms_offchain',
|
|
149
|
+
'no_instruction_built',
|
|
150
|
+
input.nativeSolRateLamports === undefined ? 'native_lamports_rate_missing' : undefined,
|
|
151
|
+
input.owner === undefined ? 'owner_missing' : undefined,
|
|
152
|
+
];
|
|
153
|
+
return reasonCodes.filter(isNonEmptyString);
|
|
154
|
+
}
|
|
155
|
+
function toUnsignedIntegerString(value) {
|
|
156
|
+
if (typeof value === 'bigint')
|
|
157
|
+
return value >= 0n ? value.toString() : '-1';
|
|
158
|
+
if (typeof value === 'number')
|
|
159
|
+
return Number.isSafeInteger(value) && value >= 0 ? String(value) : '-1';
|
|
160
|
+
return /^[0-9]+$/.test(value) ? value : '-1';
|
|
161
|
+
}
|
|
162
|
+
function toSignedIntegerString(value) {
|
|
163
|
+
if (typeof value === 'bigint')
|
|
164
|
+
return value.toString();
|
|
165
|
+
if (typeof value === 'number')
|
|
166
|
+
return Number.isSafeInteger(value) ? String(value) : '0';
|
|
167
|
+
return /^-?[0-9]+$/.test(value) ? value : '0';
|
|
168
|
+
}
|
|
169
|
+
function isU64String(value) {
|
|
170
|
+
if (typeof value !== 'string' || !/^[0-9]+$/.test(value))
|
|
171
|
+
return false;
|
|
172
|
+
return BigInt(value) <= U64_MAX;
|
|
173
|
+
}
|
|
174
|
+
function isUint8(value) {
|
|
175
|
+
return Number.isInteger(value) && value >= 0 && value <= 255;
|
|
176
|
+
}
|
|
177
|
+
function isBasisPointLike(value) {
|
|
178
|
+
return Number.isInteger(value) && value >= 0 && value <= 10000;
|
|
179
|
+
}
|
|
180
|
+
function isSolanaPublicKey(value) {
|
|
181
|
+
return typeof value === 'string' && decodeBase58(value)?.length === 32;
|
|
182
|
+
}
|
|
183
|
+
function decodeBase58(value) {
|
|
184
|
+
if (value.length === 0)
|
|
185
|
+
return undefined;
|
|
186
|
+
const bytes = [0];
|
|
187
|
+
for (const char of value) {
|
|
188
|
+
const alphabetIndex = BASE58_ALPHABET.indexOf(char);
|
|
189
|
+
if (alphabetIndex === -1)
|
|
190
|
+
return undefined;
|
|
191
|
+
let carry = alphabetIndex;
|
|
192
|
+
for (let byteIndex = 0; byteIndex < bytes.length; byteIndex += 1) {
|
|
193
|
+
carry += bytes[byteIndex] * 58;
|
|
194
|
+
bytes[byteIndex] = carry & 0xff;
|
|
195
|
+
carry >>= 8;
|
|
196
|
+
}
|
|
197
|
+
while (carry > 0) {
|
|
198
|
+
bytes.push(carry & 0xff);
|
|
199
|
+
carry >>= 8;
|
|
200
|
+
}
|
|
201
|
+
}
|
|
202
|
+
for (const char of value) {
|
|
203
|
+
if (char !== '1')
|
|
204
|
+
break;
|
|
205
|
+
bytes.push(0);
|
|
206
|
+
}
|
|
207
|
+
return Uint8Array.from(bytes.reverse());
|
|
208
|
+
}
|
|
209
|
+
function utf8ByteLength(value) {
|
|
210
|
+
return new TextEncoder().encode(value).length;
|
|
211
|
+
}
|
|
212
|
+
function isNonEmptyString(value) {
|
|
213
|
+
return typeof value === 'string' && value.trim().length > 0;
|
|
214
|
+
}
|
|
@@ -0,0 +1,202 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Source-aware ranking explainability (#344, epic #336).
|
|
3
|
+
*
|
|
4
|
+
* Enriches resolve/ranking output with a typed, per-candidate explainability
|
|
5
|
+
* block so users and operators can see WHY a source/specialist was selected,
|
|
6
|
+
* rejected, or deferred — without ever blending discovery relevance into
|
|
7
|
+
* trust, safety, budget, payment, invocation, or publication decisions
|
|
8
|
+
* (`docs/DISCOVER-DECIDE-PROVE-BOUNDARIES.md`, #452).
|
|
9
|
+
*
|
|
10
|
+
* This module is PURE and read-model only: no network, no filesystem, no
|
|
11
|
+
* LLM/provider call, no MCP/tool call, no wallet/RPC action, no registry
|
|
12
|
+
* write, no publication, no payment, no trust or reputation mutation. It only
|
|
13
|
+
* explains in-memory candidates the caller already holds.
|
|
14
|
+
*
|
|
15
|
+
* Vocabulary reuse (no new words where existing ones fit):
|
|
16
|
+
* - Per-candidate lane diagnostics come from `source-diagnostics.ts`
|
|
17
|
+
* (`reddi.source-diagnostics.v1`, the #344 lane vocabulary incl.
|
|
18
|
+
* `relevance_only_not_trust`).
|
|
19
|
+
* - Gate/rejection reason codes reuse `discovery-source.ts`
|
|
20
|
+
* (`DiscoveryCandidateReasonCode`) wherever a code exists there.
|
|
21
|
+
* - The relevance boundary mirrors the #593 conformance matrix
|
|
22
|
+
* (`discoveryBoundary.scoreMeaning: 'relevance_only_not_trust'`).
|
|
23
|
+
*
|
|
24
|
+
* Fail-closed contract:
|
|
25
|
+
* - Every candidate always carries ALL required gates — including
|
|
26
|
+
* `settlement` and `attestation` — so no source kind can silently bypass
|
|
27
|
+
* settlement or attestation constraints (#344 AC).
|
|
28
|
+
* - A gate that has not produced positive evidence is `not_evaluated`, which
|
|
29
|
+
* is never treated as passed.
|
|
30
|
+
* - Relevance influences ranking ORDER only; it never changes a gate state
|
|
31
|
+
* and a high-relevance candidate with any failed gate is still `rejected`.
|
|
32
|
+
*/
|
|
33
|
+
import { type DiscoveryCandidate, type DiscoveryCandidatePolicy, type DiscoveryCandidatePolicyPreflightDecision, type DiscoveryCandidateReasonCode, type DiscoverySourceKind } from './discovery-source.js';
|
|
34
|
+
import { type SourceAwareCandidateDiagnostics } from './source-diagnostics.js';
|
|
35
|
+
import { type ProviderTrustVerificationStatus } from './provider-trust.js';
|
|
36
|
+
export declare const RANKING_EXPLAINABILITY_SCHEMA_VERSION: "reddi.ranking-explainability.v1";
|
|
37
|
+
/** Where the relevance-is-never-trust boundary is defined. */
|
|
38
|
+
export declare const RANKING_EXPLAINABILITY_BOUNDARIES_DOC_REF: "docs/DISCOVER-DECIDE-PROVE-BOUNDARIES.md";
|
|
39
|
+
/**
|
|
40
|
+
* The gates every ranked candidate must carry. `settlement` and `attestation`
|
|
41
|
+
* are structural members of this list: they exist for every source kind and
|
|
42
|
+
* cannot be removed or defaulted to passed by any caller option.
|
|
43
|
+
*/
|
|
44
|
+
export type RankingGateId = 'trust' | 'policy' | 'quote' | 'evidence' | 'payment' | 'budget' | 'settlement' | 'attestation';
|
|
45
|
+
export declare const REQUIRED_RANKING_GATES: readonly RankingGateId[];
|
|
46
|
+
/** `not_evaluated` is never treated as passed — fail closed. */
|
|
47
|
+
export type RankingGateState = 'passed' | 'failed' | 'not_evaluated';
|
|
48
|
+
export type RankingGateCell = {
|
|
49
|
+
gate: RankingGateId;
|
|
50
|
+
state: RankingGateState;
|
|
51
|
+
reasonCodes: string[];
|
|
52
|
+
summary: string;
|
|
53
|
+
};
|
|
54
|
+
/** Why a candidate ended up selected, rejected, or deferred. */
|
|
55
|
+
export type RankingSelectionState = 'selected' | 'rejected' | 'deferred';
|
|
56
|
+
export type RankingRejectionReason = {
|
|
57
|
+
gate: RankingGateId;
|
|
58
|
+
code: string;
|
|
59
|
+
summary: string;
|
|
60
|
+
};
|
|
61
|
+
export type RankingCandidateHealthInput = {
|
|
62
|
+
/** Endpoint health as recorded by the discovery surface; never probed here. */
|
|
63
|
+
endpointHealth?: 'pass' | 'fail' | 'degraded' | 'not_probed';
|
|
64
|
+
/** When the discovery snapshot backing this candidate was generated. */
|
|
65
|
+
snapshotGeneratedAt?: string;
|
|
66
|
+
};
|
|
67
|
+
/**
|
|
68
|
+
* Prior receipt/attestation/settlement EVIDENCE the caller already holds
|
|
69
|
+
* (e.g. verified receipts and evidence archive records). References only — this
|
|
70
|
+
* module never creates, verifies, or settles anything.
|
|
71
|
+
*/
|
|
72
|
+
export type RankingCandidateEvidenceInput = {
|
|
73
|
+
receiptCount?: number;
|
|
74
|
+
attestationCount?: number;
|
|
75
|
+
settlementReceiptRefs?: string[];
|
|
76
|
+
attestationRefs?: string[];
|
|
77
|
+
};
|
|
78
|
+
export type RankingCandidateExplainabilityOptions = {
|
|
79
|
+
/** RAP policy; when present the policy preflight is evaluated here. */
|
|
80
|
+
policy?: DiscoveryCandidatePolicy;
|
|
81
|
+
/** A preflight decision the caller already evaluated (wins over `policy`). */
|
|
82
|
+
policyDecision?: DiscoveryCandidatePolicyPreflightDecision;
|
|
83
|
+
/** Fields the ranking query matched on, when the search surface knows them. */
|
|
84
|
+
matchedFields?: string[];
|
|
85
|
+
health?: RankingCandidateHealthInput;
|
|
86
|
+
evidence?: RankingCandidateEvidenceInput;
|
|
87
|
+
};
|
|
88
|
+
export type RankingCandidateExplainability = {
|
|
89
|
+
schemaVersion: typeof RANKING_EXPLAINABILITY_SCHEMA_VERSION;
|
|
90
|
+
/** Source identity: who/where this candidate came from. */
|
|
91
|
+
sourceIdentity: {
|
|
92
|
+
identifier: string;
|
|
93
|
+
name: string;
|
|
94
|
+
sourceKind: DiscoverySourceKind;
|
|
95
|
+
publisher?: {
|
|
96
|
+
id: string;
|
|
97
|
+
name?: string;
|
|
98
|
+
domain?: string;
|
|
99
|
+
};
|
|
100
|
+
url?: string;
|
|
101
|
+
endpoint?: string;
|
|
102
|
+
rawSnapshotRef?: string;
|
|
103
|
+
};
|
|
104
|
+
/** Capability match: search/ranking relevance only — never trust. */
|
|
105
|
+
capabilityMatch: {
|
|
106
|
+
resourceType: string;
|
|
107
|
+
mediaType: string;
|
|
108
|
+
relevanceScore?: number;
|
|
109
|
+
scoreMeaning: 'relevance_only_not_trust';
|
|
110
|
+
matchedFields: string[];
|
|
111
|
+
summary: string;
|
|
112
|
+
};
|
|
113
|
+
/** Trust state as RAP recorded it; external claims are never verified here. */
|
|
114
|
+
trustState: {
|
|
115
|
+
status: ProviderTrustVerificationStatus | 'missing';
|
|
116
|
+
reasonCodes: string[];
|
|
117
|
+
failureReasons: string[];
|
|
118
|
+
summary: string;
|
|
119
|
+
};
|
|
120
|
+
/** Payment policy fit (quote/asset/network/budget) from the Decide lane. */
|
|
121
|
+
paymentPolicyFit: {
|
|
122
|
+
quote?: {
|
|
123
|
+
amount: string;
|
|
124
|
+
asset: string;
|
|
125
|
+
network: string;
|
|
126
|
+
};
|
|
127
|
+
allowed?: boolean;
|
|
128
|
+
reasonCodes: DiscoveryCandidateReasonCode[];
|
|
129
|
+
summary: string;
|
|
130
|
+
};
|
|
131
|
+
/** Health/freshness as recorded by the discovery snapshot; never probed. */
|
|
132
|
+
healthFreshness: {
|
|
133
|
+
endpointHealth: 'pass' | 'fail' | 'degraded' | 'not_probed';
|
|
134
|
+
freshness: 'snapshot_backed' | 'unknown';
|
|
135
|
+
snapshotGeneratedAt?: string;
|
|
136
|
+
snapshotRef?: string;
|
|
137
|
+
summary: string;
|
|
138
|
+
};
|
|
139
|
+
/** All required gates, always present, fail closed. */
|
|
140
|
+
gates: RankingGateCell[];
|
|
141
|
+
/** Failed gates flattened into displayable rejection reasons. */
|
|
142
|
+
rejectionReasons: RankingRejectionReason[];
|
|
143
|
+
selection: {
|
|
144
|
+
state: RankingSelectionState;
|
|
145
|
+
/** Ranking order comes from relevance only; gates never reorder. */
|
|
146
|
+
rankInfluencedByGates: false;
|
|
147
|
+
summary: string;
|
|
148
|
+
};
|
|
149
|
+
/** The composed #344 lane diagnostics (`reddi.source-diagnostics.v1`). */
|
|
150
|
+
diagnostics: SourceAwareCandidateDiagnostics;
|
|
151
|
+
boundary: {
|
|
152
|
+
scoreMeaning: 'relevance_only_not_trust';
|
|
153
|
+
relevanceInfluencedGates: false;
|
|
154
|
+
boundariesDocRef: typeof RANKING_EXPLAINABILITY_BOUNDARIES_DOC_REF;
|
|
155
|
+
};
|
|
156
|
+
/** Explainability is read-only; it authorizes nothing. */
|
|
157
|
+
guardrails: {
|
|
158
|
+
trustGranted: false;
|
|
159
|
+
invocationAuthorized: false;
|
|
160
|
+
paymentAuthorized: false;
|
|
161
|
+
publicationAuthorized: false;
|
|
162
|
+
settlementBypassPossible: false;
|
|
163
|
+
attestationBypassPossible: false;
|
|
164
|
+
};
|
|
165
|
+
};
|
|
166
|
+
export type RankedCandidateExplanation = {
|
|
167
|
+
/** 1-based position, assigned by relevance ordering only. */
|
|
168
|
+
rank: number;
|
|
169
|
+
explainability: RankingCandidateExplainability;
|
|
170
|
+
};
|
|
171
|
+
export type SourceRankingExplainabilityReport = {
|
|
172
|
+
schemaVersion: typeof RANKING_EXPLAINABILITY_SCHEMA_VERSION;
|
|
173
|
+
generatedAt?: string;
|
|
174
|
+
ordering: 'relevance_desc_then_identifier_asc';
|
|
175
|
+
total: number;
|
|
176
|
+
candidates: RankedCandidateExplanation[];
|
|
177
|
+
boundary: RankingCandidateExplainability['boundary'];
|
|
178
|
+
guardrails: RankingCandidateExplainability['guardrails'];
|
|
179
|
+
};
|
|
180
|
+
export type ExplainSourceRankingOptions = {
|
|
181
|
+
policy?: DiscoveryCandidatePolicy;
|
|
182
|
+
generatedAt?: string;
|
|
183
|
+
/** Per-candidate inputs keyed by candidate identifier. */
|
|
184
|
+
perCandidate?: Record<string, Omit<RankingCandidateExplainabilityOptions, 'policy'>>;
|
|
185
|
+
};
|
|
186
|
+
/**
|
|
187
|
+
* Derive the `reddi.ranking-explainability.v1` block for one candidate.
|
|
188
|
+
*
|
|
189
|
+
* All eight required gates are always emitted; there is no option to omit,
|
|
190
|
+
* override, or pre-pass a gate. Settlement and attestation gates only pass on
|
|
191
|
+
* explicit caller-held evidence references.
|
|
192
|
+
*/
|
|
193
|
+
export declare function deriveRankingCandidateExplainability(candidate: DiscoveryCandidate, options?: RankingCandidateExplainabilityOptions): RankingCandidateExplainability;
|
|
194
|
+
/**
|
|
195
|
+
* Enrich a resolve/ranking candidate list with per-candidate explainability.
|
|
196
|
+
*
|
|
197
|
+
* Ordering is relevance-descending (ties broken by identifier) and is the ONLY
|
|
198
|
+
* thing relevance controls: rejected candidates keep their relevance rank and
|
|
199
|
+
* are marked `rejected` with reasons instead of being silently re-ordered or
|
|
200
|
+
* hidden.
|
|
201
|
+
*/
|
|
202
|
+
export declare function explainSourceRanking(candidates: DiscoveryCandidate[], options?: ExplainSourceRankingOptions): SourceRankingExplainabilityReport;
|