dsh-harness-reflex 0.1.0 → 0.3.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/README.md +20 -6
- package/client.js +3511 -185
- package/dist/attribution.d.ts +266 -0
- package/dist/attribution.js +238 -0
- package/dist/attribution.js.map +1 -0
- package/dist/bridge.d.ts +311 -13
- package/dist/bridge.js +714 -42
- package/dist/bridge.js.map +1 -1
- package/dist/client-bundle.js +4 -1
- package/dist/client-bundle.js.map +1 -1
- package/dist/command.js +10 -0
- package/dist/command.js.map +1 -1
- package/dist/config.d.ts +530 -22
- package/dist/config.js +808 -27
- package/dist/config.js.map +1 -1
- package/dist/delegation-dispatch.d.ts +132 -0
- package/dist/delegation-dispatch.js +186 -0
- package/dist/delegation-dispatch.js.map +1 -0
- package/dist/delegation-health.d.ts +131 -0
- package/dist/delegation-health.js +97 -0
- package/dist/delegation-health.js.map +1 -0
- package/dist/delegation.d.ts +148 -0
- package/dist/delegation.js +186 -0
- package/dist/delegation.js.map +1 -0
- package/dist/effort-delegation.d.ts +144 -0
- package/dist/effort-delegation.js +280 -0
- package/dist/effort-delegation.js.map +1 -0
- package/dist/effort.d.ts +141 -0
- package/dist/effort.js +251 -9
- package/dist/effort.js.map +1 -1
- package/dist/host-patch.d.ts +156 -0
- package/dist/host-patch.js +534 -0
- package/dist/host-patch.js.map +1 -0
- package/dist/index.d.ts +12 -3
- package/dist/index.js +99 -7
- package/dist/index.js.map +1 -1
- package/dist/interventions.d.ts +98 -373
- package/dist/interventions.js +442 -1702
- package/dist/interventions.js.map +1 -1
- package/dist/panel-api.d.ts +328 -4
- package/dist/panel-api.js +322 -15
- package/dist/panel-api.js.map +1 -1
- package/dist/panel-mount.d.ts +81 -22
- package/dist/panel-mount.js +228 -7
- package/dist/panel-mount.js.map +1 -1
- package/dist/routing.d.ts +23 -18
- package/dist/routing.js +471 -153
- package/dist/routing.js.map +1 -1
- package/dist/session-audit.d.ts +70 -0
- package/dist/session-audit.js +73 -0
- package/dist/session-audit.js.map +1 -1
- package/dist/systemone-probe.d.ts +114 -0
- package/dist/systemone-probe.js +383 -0
- package/dist/systemone-probe.js.map +1 -0
- package/dist/testing.d.ts +212 -7
- package/dist/testing.js +333 -27
- package/dist/testing.js.map +1 -1
- package/dist/tools.d.ts +109 -3
- package/dist/tools.js +103 -4
- package/dist/tools.js.map +1 -1
- package/dist/unconfigured-backend.d.ts +72 -0
- package/dist/unconfigured-backend.js +94 -0
- package/dist/unconfigured-backend.js.map +1 -0
- package/dist/vendor/harness-reflex/backend/factory.d.ts +31 -1
- package/dist/vendor/harness-reflex/backend/factory.js +18 -3
- package/dist/vendor/harness-reflex/backend/factory.js.map +1 -1
- package/dist/vendor/harness-reflex/backend/jev.d.ts +20 -0
- package/dist/vendor/harness-reflex/backend/jev.js +11 -4
- package/dist/vendor/harness-reflex/backend/jev.js.map +1 -1
- package/dist/vendor/harness-reflex/backend/simple-jev.d.ts +16 -0
- package/dist/vendor/harness-reflex/backend/simple-jev.js +17 -6
- package/dist/vendor/harness-reflex/backend/simple-jev.js.map +1 -1
- package/dist/vendor/harness-reflex/core/closing.d.ts +90 -0
- package/dist/vendor/harness-reflex/core/closing.js +111 -0
- package/dist/vendor/harness-reflex/core/closing.js.map +1 -0
- package/dist/vendor/harness-reflex/core/evidence.d.ts +119 -0
- package/dist/vendor/harness-reflex/core/evidence.js +209 -0
- package/dist/vendor/harness-reflex/core/evidence.js.map +1 -0
- package/dist/vendor/harness-reflex/core/judge.d.ts +221 -0
- package/dist/vendor/harness-reflex/core/judge.js +251 -0
- package/dist/vendor/harness-reflex/core/judge.js.map +1 -0
- package/dist/vendor/harness-reflex/core/orchestrate-closing.d.ts +237 -0
- package/dist/vendor/harness-reflex/core/orchestrate-closing.js +250 -0
- package/dist/vendor/harness-reflex/core/orchestrate-closing.js.map +1 -0
- package/dist/vendor/harness-reflex/core/orchestrate-correction.d.ts +209 -0
- package/dist/vendor/harness-reflex/core/orchestrate-correction.js +141 -0
- package/dist/vendor/harness-reflex/core/orchestrate-correction.js.map +1 -0
- package/dist/vendor/harness-reflex/core/orchestrate-host.d.ts +225 -0
- package/dist/vendor/harness-reflex/core/orchestrate-host.js +80 -0
- package/dist/vendor/harness-reflex/core/orchestrate-host.js.map +1 -0
- package/dist/vendor/harness-reflex/core/orchestrate-stagnation.d.ts +259 -0
- package/dist/vendor/harness-reflex/core/orchestrate-stagnation.js +270 -0
- package/dist/vendor/harness-reflex/core/orchestrate-stagnation.js.map +1 -0
- package/dist/vendor/harness-reflex/core/orchestrate.d.ts +357 -0
- package/dist/vendor/harness-reflex/core/orchestrate.js +418 -0
- package/dist/vendor/harness-reflex/core/orchestrate.js.map +1 -0
- package/dist/vendor/harness-reflex/core/policy.d.ts +122 -0
- package/dist/vendor/harness-reflex/core/policy.js +102 -0
- package/dist/vendor/harness-reflex/core/policy.js.map +1 -0
- package/dist/vendor/harness-reflex/core/prune-plan.d.ts +141 -0
- package/dist/vendor/harness-reflex/core/prune-plan.js +390 -0
- package/dist/vendor/harness-reflex/core/prune-plan.js.map +1 -0
- package/dist/vendor/harness-reflex/core/text.d.ts +36 -0
- package/dist/vendor/harness-reflex/core/text.js +66 -0
- package/dist/vendor/harness-reflex/core/text.js.map +1 -0
- package/dist/vendor/harness-reflex/ports/audit.d.ts +18 -0
- package/dist/vendor/harness-reflex/ports/audit.js +11 -0
- package/dist/vendor/harness-reflex/ports/audit.js.map +1 -0
- package/dist/vendor/harness-reflex/ports/clock.d.ts +14 -0
- package/dist/vendor/harness-reflex/ports/clock.js +11 -0
- package/dist/vendor/harness-reflex/ports/clock.js.map +1 -0
- package/dist/vendor/harness-reflex/ports/decision.d.ts +75 -0
- package/dist/vendor/harness-reflex/ports/decision.js +2 -0
- package/dist/vendor/harness-reflex/ports/decision.js.map +1 -0
- package/dist/vendor/harness-reflex/ports/index.d.ts +14 -0
- package/dist/vendor/harness-reflex/ports/index.js +2 -0
- package/dist/vendor/harness-reflex/ports/index.js.map +1 -0
- package/dist/vendor/harness-reflex/ports/log.d.ts +22 -0
- package/dist/vendor/harness-reflex/ports/log.js +12 -0
- package/dist/vendor/harness-reflex/ports/log.js.map +1 -0
- package/dist/vendor/harness-reflex/ports/state.d.ts +46 -0
- package/dist/vendor/harness-reflex/ports/state.js +13 -0
- package/dist/vendor/harness-reflex/ports/state.js.map +1 -0
- package/package.json +25 -13
|
@@ -0,0 +1,266 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Per-call provenance of one System One decision: which connection and which
|
|
3
|
+
* requested model were in force **when the call was dispatched**, and where the
|
|
4
|
+
* answer really came from.
|
|
5
|
+
*
|
|
6
|
+
* ## Why this module exists (g-068)
|
|
7
|
+
*
|
|
8
|
+
* A session switched the active System One profile three times and then to a
|
|
9
|
+
* model that does not exist. Every call still answered, and the tool payloads
|
|
10
|
+
* said nothing about the connection or the model, so the only honest sentence a
|
|
11
|
+
* reader could write was "no model is shown". The reader cannot be expected to
|
|
12
|
+
* reconstruct provenance from a payload that omits it, and the ledger used to
|
|
13
|
+
* record a *backend class name* (`mock-heuristic-v1`, `system-one-jev`) that is
|
|
14
|
+
* neither the connection the user named nor the model that was asked for.
|
|
15
|
+
*
|
|
16
|
+
* ## The four facts, and what each one may claim
|
|
17
|
+
*
|
|
18
|
+
* - `connectionName` — the name of the System One connection (the profile) that
|
|
19
|
+
* was in force at dispatch. This is the one identity a human authored, so it
|
|
20
|
+
* is what "which connection answered?" must answer. It is *not* the backend
|
|
21
|
+
* class and *not* the main model the session itself is running on.
|
|
22
|
+
* - `model` — the model id the runtime **requested** for this call. It is a
|
|
23
|
+
* request, never an observation: a gateway may rewrite it, and this plugin
|
|
24
|
+
* never sees what an upstream really served. Nothing here may ever be
|
|
25
|
+
* presented as "the model that answered".
|
|
26
|
+
* - `source` — where the answer came from, in states that must never be
|
|
27
|
+
* collapsed: `remote`, `local` (this connection sends nothing),
|
|
28
|
+
* `local-fallback` (a remote attempt happened and its failure was absorbed
|
|
29
|
+
* locally) and `rejected` (the call failed and no answer was invented). A
|
|
30
|
+
* fifth value, `unknown`, is what a call reports when nothing it could observe
|
|
31
|
+
* *proves* any of the others — see {@link classifyEvidence}. It is a real
|
|
32
|
+
* state, not a placeholder: a backend that publishes no failure record leaves
|
|
33
|
+
* a settled call with no positive evidence that a request was answered, and
|
|
34
|
+
* claiming `remote` there is exactly the falsehood this goal removes.
|
|
35
|
+
* - `detail` — the reason a non-remote call is non-remote, kept so a reader can
|
|
36
|
+
* tell "no connection configured" from "the gateway refused the model".
|
|
37
|
+
*
|
|
38
|
+
* ## Snapshot at dispatch, never re-read
|
|
39
|
+
*
|
|
40
|
+
* {@link callIdentity} is taken *before* the backend is awaited and carried
|
|
41
|
+
* through the payload and the ledger entry. A profile switch, a concurrent
|
|
42
|
+
* in-flight call, or a later history read therefore cannot restate an older
|
|
43
|
+
* call: the answer keeps the identity it was asked under. That is the property
|
|
44
|
+
* the `switch and in-flight` tests pin.
|
|
45
|
+
*
|
|
46
|
+
* ## What this module must never do
|
|
47
|
+
*
|
|
48
|
+
* It never reads or renders a key, an endpoint's credentials, or the main
|
|
49
|
+
* model. `apiKeyEnv` is deliberately absent from {@link CallIdentity}: the
|
|
50
|
+
* *name* of a variable is harmless but it is also not provenance, and a caller
|
|
51
|
+
* that wants the connection's address/selector has the panel for that.
|
|
52
|
+
*
|
|
53
|
+
* @module dsh-reflex/attribution
|
|
54
|
+
*/
|
|
55
|
+
import type { ResolvedSystemOneConfig } from './config.js';
|
|
56
|
+
/**
|
|
57
|
+
* Where one answer came from.
|
|
58
|
+
*
|
|
59
|
+
* The states g-068 must keep apart, plus `unknown` for a caller that can prove
|
|
60
|
+
* none of them:
|
|
61
|
+
*
|
|
62
|
+
* - `remote` — the connection was asked and answered;
|
|
63
|
+
* - `local` — this connection sends no request at all (the in-process mock, or
|
|
64
|
+
* an activation with no profile), so "remote" would be a lie;
|
|
65
|
+
* - `local-fallback` — a remote attempt was made and **failed**, and the answer
|
|
66
|
+
* was produced locally afterwards. This is the "远端拒绝后本地降级" case;
|
|
67
|
+
* - `rejected` — the remote attempt failed and the call produced no decision of
|
|
68
|
+
* its own (it threw), or produced only a fail-closed verdict.
|
|
69
|
+
*
|
|
70
|
+
* `local-fallback` and `rejected` are both failures of the remote attempt and
|
|
71
|
+
* must never be rendered as a remote success.
|
|
72
|
+
*/
|
|
73
|
+
export type CallSource = 'remote' | 'local' | 'local-fallback' | 'rejected' | 'unknown';
|
|
74
|
+
/** Provenance of one decision call, as taken at dispatch. */
|
|
75
|
+
export interface CallIdentity {
|
|
76
|
+
/**
|
|
77
|
+
* Name of the System One connection in force at dispatch.
|
|
78
|
+
*
|
|
79
|
+
* The active profile's name, or one of the two synthetic names this module
|
|
80
|
+
* defines when no profile exists: `mock` for a deployment that explicitly
|
|
81
|
+
* chose the in-process implementation, `unconfigured` for an activation that
|
|
82
|
+
* has no connection at all. Never the backend class name.
|
|
83
|
+
*/
|
|
84
|
+
readonly connectionName: string;
|
|
85
|
+
/**
|
|
86
|
+
* The model id this call **requested**, or `null` when the connection names
|
|
87
|
+
* none (nothing was sent, or the backend's own default applies).
|
|
88
|
+
*
|
|
89
|
+
* A request, never an observation: this plugin cannot see whether an upstream
|
|
90
|
+
* served, rewrote, or ignored it. Renderers must keep that wording.
|
|
91
|
+
*/
|
|
92
|
+
readonly requestedModel: string | null;
|
|
93
|
+
}
|
|
94
|
+
/** The connection name used when the deployment explicitly chose the mock. */
|
|
95
|
+
export declare const MOCK_CONNECTION_NAME = "mock";
|
|
96
|
+
/** The connection name used when the activation has no connection at all. */
|
|
97
|
+
export declare const UNCONFIGURED_CONNECTION_NAME = "unconfigured";
|
|
98
|
+
/**
|
|
99
|
+
* Read the identity of the connection an activation would use right now.
|
|
100
|
+
*
|
|
101
|
+
* Pure and synchronous on purpose: the caller takes it at dispatch, before any
|
|
102
|
+
* request leaves, so what it reports is the connection the call was *asked*
|
|
103
|
+
* under rather than whatever the live config says when the answer arrives.
|
|
104
|
+
*
|
|
105
|
+
* The order matters and mirrors {@link createBackend}: an explicit `mock`
|
|
106
|
+
* outranks the "no active profile" rule (the mock never uses a profile), and an
|
|
107
|
+
* `unconfigured` connection is named as such rather than by the profile the
|
|
108
|
+
* document happens to carry.
|
|
109
|
+
* @param systemOne - the resolved connection block currently in force.
|
|
110
|
+
* @param backendSelector - the deployment's backend selector (`auto` when unauthored).
|
|
111
|
+
* @returns the identity to carry through the payload and the ledger entry.
|
|
112
|
+
*/
|
|
113
|
+
export declare function callIdentity(systemOne: ResolvedSystemOneConfig, backendSelector: ResolvedSystemOneConfig['backend'] | undefined): CallIdentity;
|
|
114
|
+
/** One call's provenance as it appears in a tool payload. */
|
|
115
|
+
export interface Attribution {
|
|
116
|
+
/**
|
|
117
|
+
* Name of the System One connection the call used.
|
|
118
|
+
*
|
|
119
|
+
* The profile the user activated — not the backend class, and not the main
|
|
120
|
+
* model this session runs on.
|
|
121
|
+
*/
|
|
122
|
+
connectionName: string;
|
|
123
|
+
/**
|
|
124
|
+
* The model id this call requested from that connection; `null` when the
|
|
125
|
+
* connection names none.
|
|
126
|
+
*
|
|
127
|
+
* A request, not an observation: whether an upstream served or rewrote it is
|
|
128
|
+
* unknown to this plugin.
|
|
129
|
+
*/
|
|
130
|
+
requestedModel: string | null;
|
|
131
|
+
/** Where the answer came from (see {@link CallSource}). */
|
|
132
|
+
source: CallSource;
|
|
133
|
+
/** Why the source is not `remote`; absent exactly when `source` is `remote`. */
|
|
134
|
+
detail?: string;
|
|
135
|
+
}
|
|
136
|
+
/**
|
|
137
|
+
* Classify one settled attempt into a {@link CallSource}.
|
|
138
|
+
*
|
|
139
|
+
* `answered` is the only question asked of the outcome: a call that produced a
|
|
140
|
+
* decision was answered, whatever path produced it. The reason decides between
|
|
141
|
+
* a remote answer and a local one, because a locally absorbed failure must stay
|
|
142
|
+
* distinguishable from a gateway answer.
|
|
143
|
+
* @param answered - whether the call produced a decision at all.
|
|
144
|
+
* @param failure - the absorbed failure, when one happened.
|
|
145
|
+
* @param localFallback - whether the answered value was produced locally *after*
|
|
146
|
+
* a remote attempt failed (rather than by a local-only connection).
|
|
147
|
+
* @param localOnly - whether this connection makes no request at all.
|
|
148
|
+
* @returns the source, and the detail for a non-remote one.
|
|
149
|
+
*/
|
|
150
|
+
export declare function classifySource(answered: boolean, failure: string | undefined, localFallback: boolean, localOnly: boolean): {
|
|
151
|
+
source: CallSource;
|
|
152
|
+
detail?: string;
|
|
153
|
+
};
|
|
154
|
+
/**
|
|
155
|
+
* What one dispatch could prove about where its answer came from.
|
|
156
|
+
*
|
|
157
|
+
* Every field is something the runtime *observed*; none is inferred from a
|
|
158
|
+
* request id or from the settings in force at read time.
|
|
159
|
+
*/
|
|
160
|
+
export interface SourceEvidence {
|
|
161
|
+
/** Whether the call produced a decision at all. */
|
|
162
|
+
readonly answered: boolean;
|
|
163
|
+
/** The thrown failure, when the call threw. */
|
|
164
|
+
readonly failure?: string;
|
|
165
|
+
/** Whether the answered value was produced locally after a remote failure. */
|
|
166
|
+
readonly localFallback?: boolean;
|
|
167
|
+
/** Whether this connection sends no request at all. */
|
|
168
|
+
readonly localOnly: boolean;
|
|
169
|
+
/**
|
|
170
|
+
* Whether the backend exposes a failure record this module may read.
|
|
171
|
+
*
|
|
172
|
+
* Only `JevDecisionBackend` has one. The vLLM logits backend has no
|
|
173
|
+
* `health()`, and its services absorb a gateway failure into a fail-closed
|
|
174
|
+
* verdict the same way the JEV one does — so without a record, a settled call
|
|
175
|
+
* here has **no positive evidence** that a request was made and answered.
|
|
176
|
+
*/
|
|
177
|
+
readonly healthReadable: boolean;
|
|
178
|
+
/** `consecutiveFailures` before the call, when the record is readable. */
|
|
179
|
+
readonly failuresBefore?: number;
|
|
180
|
+
/** `consecutiveFailures` after the call, when the record is readable. */
|
|
181
|
+
readonly failuresAfter?: number;
|
|
182
|
+
/** The backend's reason for its most recent failure, when readable. */
|
|
183
|
+
readonly lastFailureReason?: string;
|
|
184
|
+
/**
|
|
185
|
+
* Whether the ledger entry this call produced arrived **after** the call
|
|
186
|
+
* settled — in which case the source written on the entry cannot be trusted
|
|
187
|
+
* to be this call's.
|
|
188
|
+
*/
|
|
189
|
+
readonly entryArrivedLate?: boolean;
|
|
190
|
+
}
|
|
191
|
+
/**
|
|
192
|
+
* Classify a settled attempt from evidence, preferring `unknown` to a claim.
|
|
193
|
+
*
|
|
194
|
+
* This is {@link classifySource} with the one question the first version got
|
|
195
|
+
* wrong added: a call that resolved and *looked* remote may have had its
|
|
196
|
+
* request rejected and its failure absorbed — by the gate, or by a prune that
|
|
197
|
+
* fell back — and claiming `remote` for it is the precise falsehood g-068
|
|
198
|
+
* forbids. Three states are therefore never guessed:
|
|
199
|
+
*
|
|
200
|
+
* - a **late entry** means this call's provenance could not be tied to the
|
|
201
|
+
* entry that carried it, so the source is `unknown` (the ledger line itself
|
|
202
|
+
* also says `unknown`; the two surfaces agree);
|
|
203
|
+
* - a connection that sends nothing is `local` by construction, without asking;
|
|
204
|
+
* - a **settled, non-local call on a backend with no readable failure record**
|
|
205
|
+
* has no positive evidence for `remote`, so it is `unknown`. The fail-closed
|
|
206
|
+
* verdict the caller still receives is unchanged; only the claim about its
|
|
207
|
+
* provenance is withdrawn.
|
|
208
|
+
*
|
|
209
|
+
* Everything the first version handled keeps its old answer: a thrown call is
|
|
210
|
+
* `rejected`, a local answer after a failure is `local-fallback`, and a local
|
|
211
|
+
* path that is reported by the service itself stays `local`/`local-fallback`.
|
|
212
|
+
* @param evidence - the facts the dispatch observed.
|
|
213
|
+
* @returns the source, and the detail for a non-remote one.
|
|
214
|
+
*/
|
|
215
|
+
export declare function classifyEvidence(evidence: SourceEvidence): {
|
|
216
|
+
source: CallSource;
|
|
217
|
+
detail?: string;
|
|
218
|
+
};
|
|
219
|
+
/**
|
|
220
|
+
* Compose the payload fields one call reports.
|
|
221
|
+
* @param identity - the identity taken at dispatch.
|
|
222
|
+
* @param outcome - the classified source and detail.
|
|
223
|
+
* @returns the attribution object to spread into a tool payload or lead a ledger entry.
|
|
224
|
+
*/
|
|
225
|
+
export declare function attributionOf(identity: CallIdentity, outcome: {
|
|
226
|
+
source: CallSource;
|
|
227
|
+
detail?: string;
|
|
228
|
+
}): Attribution;
|
|
229
|
+
/**
|
|
230
|
+
* The ledger's view of one call's provenance.
|
|
231
|
+
*
|
|
232
|
+
* Flat and prefixed (`systemOneConnection`, `systemOneModel`, `systemOneSource`)
|
|
233
|
+
* rather than nested, so an existing JSONL reader that greps a single line can
|
|
234
|
+
* pick the facts out without knowing the nesting, and so `backend` keeps its
|
|
235
|
+
* historical meaning ("which implementation class answered") beside them. The
|
|
236
|
+
* three are the facts g-068 requires the ledger to carry; none of them is ever
|
|
237
|
+
* inferred from a request id, and `systemOneModel` is the *requested* id.
|
|
238
|
+
*/
|
|
239
|
+
export interface LedgerAttribution {
|
|
240
|
+
/** Connection name in force at dispatch (see {@link CallIdentity.connectionName}). */
|
|
241
|
+
systemOneConnection: string;
|
|
242
|
+
/** Model id the call requested, `null` when the connection names none. */
|
|
243
|
+
systemOneModel: string | null;
|
|
244
|
+
/** Where the answer came from. */
|
|
245
|
+
systemOneSource: CallSource;
|
|
246
|
+
/** Why the source is not `remote`; absent when it is. */
|
|
247
|
+
systemOneDetail?: string;
|
|
248
|
+
}
|
|
249
|
+
/**
|
|
250
|
+
* Project an attribution onto the ledger's flat fields.
|
|
251
|
+
* @param attribution - the call's attribution.
|
|
252
|
+
* @returns the flat ledger fields.
|
|
253
|
+
*/
|
|
254
|
+
export declare function ledgerAttribution(attribution: Attribution): LedgerAttribution;
|
|
255
|
+
/**
|
|
256
|
+
* Render one attribution as the single line `/reflex-ledger` prints.
|
|
257
|
+
*
|
|
258
|
+
* Bilingual and compact: the connection name, the requested model (marked as a
|
|
259
|
+
* request), and — for a non-remote call — the source with its reason. A `remote`
|
|
260
|
+
* call prints no source word, because "answered by the connection as asked" is
|
|
261
|
+
* the only reading that needs no warning; a local fallback or a rejection always
|
|
262
|
+
* says so.
|
|
263
|
+
* @param fields - the flat ledger fields of one entry.
|
|
264
|
+
* @returns the line segment, or `undefined` for an entry that predates g-068.
|
|
265
|
+
*/
|
|
266
|
+
export declare function describeAttribution(fields: Partial<LedgerAttribution>): string | undefined;
|
|
@@ -0,0 +1,238 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Per-call provenance of one System One decision: which connection and which
|
|
3
|
+
* requested model were in force **when the call was dispatched**, and where the
|
|
4
|
+
* answer really came from.
|
|
5
|
+
*
|
|
6
|
+
* ## Why this module exists (g-068)
|
|
7
|
+
*
|
|
8
|
+
* A session switched the active System One profile three times and then to a
|
|
9
|
+
* model that does not exist. Every call still answered, and the tool payloads
|
|
10
|
+
* said nothing about the connection or the model, so the only honest sentence a
|
|
11
|
+
* reader could write was "no model is shown". The reader cannot be expected to
|
|
12
|
+
* reconstruct provenance from a payload that omits it, and the ledger used to
|
|
13
|
+
* record a *backend class name* (`mock-heuristic-v1`, `system-one-jev`) that is
|
|
14
|
+
* neither the connection the user named nor the model that was asked for.
|
|
15
|
+
*
|
|
16
|
+
* ## The four facts, and what each one may claim
|
|
17
|
+
*
|
|
18
|
+
* - `connectionName` — the name of the System One connection (the profile) that
|
|
19
|
+
* was in force at dispatch. This is the one identity a human authored, so it
|
|
20
|
+
* is what "which connection answered?" must answer. It is *not* the backend
|
|
21
|
+
* class and *not* the main model the session itself is running on.
|
|
22
|
+
* - `model` — the model id the runtime **requested** for this call. It is a
|
|
23
|
+
* request, never an observation: a gateway may rewrite it, and this plugin
|
|
24
|
+
* never sees what an upstream really served. Nothing here may ever be
|
|
25
|
+
* presented as "the model that answered".
|
|
26
|
+
* - `source` — where the answer came from, in states that must never be
|
|
27
|
+
* collapsed: `remote`, `local` (this connection sends nothing),
|
|
28
|
+
* `local-fallback` (a remote attempt happened and its failure was absorbed
|
|
29
|
+
* locally) and `rejected` (the call failed and no answer was invented). A
|
|
30
|
+
* fifth value, `unknown`, is what a call reports when nothing it could observe
|
|
31
|
+
* *proves* any of the others — see {@link classifyEvidence}. It is a real
|
|
32
|
+
* state, not a placeholder: a backend that publishes no failure record leaves
|
|
33
|
+
* a settled call with no positive evidence that a request was answered, and
|
|
34
|
+
* claiming `remote` there is exactly the falsehood this goal removes.
|
|
35
|
+
* - `detail` — the reason a non-remote call is non-remote, kept so a reader can
|
|
36
|
+
* tell "no connection configured" from "the gateway refused the model".
|
|
37
|
+
*
|
|
38
|
+
* ## Snapshot at dispatch, never re-read
|
|
39
|
+
*
|
|
40
|
+
* {@link callIdentity} is taken *before* the backend is awaited and carried
|
|
41
|
+
* through the payload and the ledger entry. A profile switch, a concurrent
|
|
42
|
+
* in-flight call, or a later history read therefore cannot restate an older
|
|
43
|
+
* call: the answer keeps the identity it was asked under. That is the property
|
|
44
|
+
* the `switch and in-flight` tests pin.
|
|
45
|
+
*
|
|
46
|
+
* ## What this module must never do
|
|
47
|
+
*
|
|
48
|
+
* It never reads or renders a key, an endpoint's credentials, or the main
|
|
49
|
+
* model. `apiKeyEnv` is deliberately absent from {@link CallIdentity}: the
|
|
50
|
+
* *name* of a variable is harmless but it is also not provenance, and a caller
|
|
51
|
+
* that wants the connection's address/selector has the panel for that.
|
|
52
|
+
*
|
|
53
|
+
* @module dsh-reflex/attribution
|
|
54
|
+
*/
|
|
55
|
+
/** The connection name used when the deployment explicitly chose the mock. */
|
|
56
|
+
export const MOCK_CONNECTION_NAME = 'mock';
|
|
57
|
+
/** The connection name used when the activation has no connection at all. */
|
|
58
|
+
export const UNCONFIGURED_CONNECTION_NAME = 'unconfigured';
|
|
59
|
+
/**
|
|
60
|
+
* Read the identity of the connection an activation would use right now.
|
|
61
|
+
*
|
|
62
|
+
* Pure and synchronous on purpose: the caller takes it at dispatch, before any
|
|
63
|
+
* request leaves, so what it reports is the connection the call was *asked*
|
|
64
|
+
* under rather than whatever the live config says when the answer arrives.
|
|
65
|
+
*
|
|
66
|
+
* The order matters and mirrors {@link createBackend}: an explicit `mock`
|
|
67
|
+
* outranks the "no active profile" rule (the mock never uses a profile), and an
|
|
68
|
+
* `unconfigured` connection is named as such rather than by the profile the
|
|
69
|
+
* document happens to carry.
|
|
70
|
+
* @param systemOne - the resolved connection block currently in force.
|
|
71
|
+
* @param backendSelector - the deployment's backend selector (`auto` when unauthored).
|
|
72
|
+
* @returns the identity to carry through the payload and the ledger entry.
|
|
73
|
+
*/
|
|
74
|
+
export function callIdentity(systemOne, backendSelector) {
|
|
75
|
+
if (backendSelector === 'mock' || systemOne.backend === 'mock') {
|
|
76
|
+
return { connectionName: MOCK_CONNECTION_NAME, requestedModel: null };
|
|
77
|
+
}
|
|
78
|
+
if (systemOne.unconfigured !== undefined || systemOne.active === undefined) {
|
|
79
|
+
return { connectionName: UNCONFIGURED_CONNECTION_NAME, requestedModel: null };
|
|
80
|
+
}
|
|
81
|
+
return { connectionName: systemOne.active, requestedModel: systemOne.model ?? null };
|
|
82
|
+
}
|
|
83
|
+
/**
|
|
84
|
+
* Classify one settled attempt into a {@link CallSource}.
|
|
85
|
+
*
|
|
86
|
+
* `answered` is the only question asked of the outcome: a call that produced a
|
|
87
|
+
* decision was answered, whatever path produced it. The reason decides between
|
|
88
|
+
* a remote answer and a local one, because a locally absorbed failure must stay
|
|
89
|
+
* distinguishable from a gateway answer.
|
|
90
|
+
* @param answered - whether the call produced a decision at all.
|
|
91
|
+
* @param failure - the absorbed failure, when one happened.
|
|
92
|
+
* @param localFallback - whether the answered value was produced locally *after*
|
|
93
|
+
* a remote attempt failed (rather than by a local-only connection).
|
|
94
|
+
* @param localOnly - whether this connection makes no request at all.
|
|
95
|
+
* @returns the source, and the detail for a non-remote one.
|
|
96
|
+
*/
|
|
97
|
+
export function classifySource(answered, failure, localFallback, localOnly) {
|
|
98
|
+
if (failure !== undefined) {
|
|
99
|
+
// A remote attempt happened and its request failed. What the caller did with
|
|
100
|
+
// that failure is the distinction the goal exists to preserve: an answer
|
|
101
|
+
// produced *locally afterwards* is a local fallback (a remote rejection that
|
|
102
|
+
// was absorbed), while a call with no answer is a rejection. Neither may be
|
|
103
|
+
// described as a remote success.
|
|
104
|
+
return answered && localFallback
|
|
105
|
+
? { source: 'local-fallback', detail: failure }
|
|
106
|
+
: { source: 'rejected', detail: failure };
|
|
107
|
+
}
|
|
108
|
+
if (!answered)
|
|
109
|
+
return { source: 'rejected', detail: 'the call produced no decision' };
|
|
110
|
+
// A connection that sends nothing is local by construction, not by fallback:
|
|
111
|
+
// the two read differently in a ledger and mean different things to a user.
|
|
112
|
+
if (localOnly)
|
|
113
|
+
return { source: 'local', detail: `no request is sent by this connection` };
|
|
114
|
+
if (localFallback)
|
|
115
|
+
return { source: 'local-fallback', detail: 'the answer was produced locally, not by System One' };
|
|
116
|
+
return { source: 'remote' };
|
|
117
|
+
}
|
|
118
|
+
/**
|
|
119
|
+
* Classify a settled attempt from evidence, preferring `unknown` to a claim.
|
|
120
|
+
*
|
|
121
|
+
* This is {@link classifySource} with the one question the first version got
|
|
122
|
+
* wrong added: a call that resolved and *looked* remote may have had its
|
|
123
|
+
* request rejected and its failure absorbed — by the gate, or by a prune that
|
|
124
|
+
* fell back — and claiming `remote` for it is the precise falsehood g-068
|
|
125
|
+
* forbids. Three states are therefore never guessed:
|
|
126
|
+
*
|
|
127
|
+
* - a **late entry** means this call's provenance could not be tied to the
|
|
128
|
+
* entry that carried it, so the source is `unknown` (the ledger line itself
|
|
129
|
+
* also says `unknown`; the two surfaces agree);
|
|
130
|
+
* - a connection that sends nothing is `local` by construction, without asking;
|
|
131
|
+
* - a **settled, non-local call on a backend with no readable failure record**
|
|
132
|
+
* has no positive evidence for `remote`, so it is `unknown`. The fail-closed
|
|
133
|
+
* verdict the caller still receives is unchanged; only the claim about its
|
|
134
|
+
* provenance is withdrawn.
|
|
135
|
+
*
|
|
136
|
+
* Everything the first version handled keeps its old answer: a thrown call is
|
|
137
|
+
* `rejected`, a local answer after a failure is `local-fallback`, and a local
|
|
138
|
+
* path that is reported by the service itself stays `local`/`local-fallback`.
|
|
139
|
+
* @param evidence - the facts the dispatch observed.
|
|
140
|
+
* @returns the source, and the detail for a non-remote one.
|
|
141
|
+
*/
|
|
142
|
+
export function classifyEvidence(evidence) {
|
|
143
|
+
const isLocal = evidence.localOnly;
|
|
144
|
+
if (evidence.entryArrivedLate === true) {
|
|
145
|
+
return {
|
|
146
|
+
source: isLocal ? 'local' : 'unknown',
|
|
147
|
+
...(isLocal
|
|
148
|
+
? {}
|
|
149
|
+
: { detail: 'the ledger entry for this call could not be tied to it, so its source is unproven' })
|
|
150
|
+
};
|
|
151
|
+
}
|
|
152
|
+
if (evidence.failure !== undefined)
|
|
153
|
+
return classifySource(false, evidence.failure, false, isLocal);
|
|
154
|
+
if (!evidence.answered)
|
|
155
|
+
return classifySource(false, undefined, false, isLocal);
|
|
156
|
+
if (isLocal)
|
|
157
|
+
return classifySource(true, undefined, false, true);
|
|
158
|
+
// A readable record proves a failure when the failure count rose across the
|
|
159
|
+
// call. It proves a *success* only when the backend has one and did not rise;
|
|
160
|
+
// without one, `remote` would be a guess.
|
|
161
|
+
const before = evidence.failuresBefore ?? 0;
|
|
162
|
+
const after = evidence.failuresAfter;
|
|
163
|
+
const absorbed = after !== undefined && after > before
|
|
164
|
+
? (evidence.lastFailureReason ?? 'the System One request failed')
|
|
165
|
+
: undefined;
|
|
166
|
+
if (absorbed !== undefined) {
|
|
167
|
+
// A failure the service absorbed is a rejection unless the caller says the
|
|
168
|
+
// answered value was produced *locally* afterwards. A gate that turns a
|
|
169
|
+
// gateway failure into a fail-closed `escalate` verdict made no decision of
|
|
170
|
+
// its own, so it is `rejected` — not `local-fallback`, which would claim a
|
|
171
|
+
// local judgment replaced the failed one.
|
|
172
|
+
return classifySource(true, absorbed, evidence.localFallback === true, false);
|
|
173
|
+
}
|
|
174
|
+
if (evidence.healthReadable !== true || after === undefined) {
|
|
175
|
+
return {
|
|
176
|
+
source: 'unknown',
|
|
177
|
+
detail: 'this connection exposes no failure record, so no evidence proves the request was answered'
|
|
178
|
+
};
|
|
179
|
+
}
|
|
180
|
+
return classifySource(true, undefined, evidence.localFallback === true, false);
|
|
181
|
+
}
|
|
182
|
+
/**
|
|
183
|
+
* Compose the payload fields one call reports.
|
|
184
|
+
* @param identity - the identity taken at dispatch.
|
|
185
|
+
* @param outcome - the classified source and detail.
|
|
186
|
+
* @returns the attribution object to spread into a tool payload or lead a ledger entry.
|
|
187
|
+
*/
|
|
188
|
+
export function attributionOf(identity, outcome) {
|
|
189
|
+
return {
|
|
190
|
+
connectionName: identity.connectionName,
|
|
191
|
+
requestedModel: identity.requestedModel,
|
|
192
|
+
source: outcome.source,
|
|
193
|
+
...(outcome.detail === undefined || outcome.detail === '' ? {} : { detail: outcome.detail })
|
|
194
|
+
};
|
|
195
|
+
}
|
|
196
|
+
/**
|
|
197
|
+
* Project an attribution onto the ledger's flat fields.
|
|
198
|
+
* @param attribution - the call's attribution.
|
|
199
|
+
* @returns the flat ledger fields.
|
|
200
|
+
*/
|
|
201
|
+
export function ledgerAttribution(attribution) {
|
|
202
|
+
return {
|
|
203
|
+
systemOneConnection: attribution.connectionName,
|
|
204
|
+
systemOneModel: attribution.requestedModel,
|
|
205
|
+
systemOneSource: attribution.source,
|
|
206
|
+
...(attribution.detail === undefined ? {} : { systemOneDetail: attribution.detail })
|
|
207
|
+
};
|
|
208
|
+
}
|
|
209
|
+
/**
|
|
210
|
+
* Render one attribution as the single line `/reflex-ledger` prints.
|
|
211
|
+
*
|
|
212
|
+
* Bilingual and compact: the connection name, the requested model (marked as a
|
|
213
|
+
* request), and — for a non-remote call — the source with its reason. A `remote`
|
|
214
|
+
* call prints no source word, because "answered by the connection as asked" is
|
|
215
|
+
* the only reading that needs no warning; a local fallback or a rejection always
|
|
216
|
+
* says so.
|
|
217
|
+
* @param fields - the flat ledger fields of one entry.
|
|
218
|
+
* @returns the line segment, or `undefined` for an entry that predates g-068.
|
|
219
|
+
*/
|
|
220
|
+
export function describeAttribution(fields) {
|
|
221
|
+
if (typeof fields.systemOneConnection !== 'string' || fields.systemOneConnection === '')
|
|
222
|
+
return undefined;
|
|
223
|
+
const model = fields.systemOneModel === null || fields.systemOneModel === undefined ? '无模型 / none' : fields.systemOneModel;
|
|
224
|
+
const head = `${fields.systemOneConnection} · 请求模型 ${model}`;
|
|
225
|
+
switch (fields.systemOneSource) {
|
|
226
|
+
case 'local':
|
|
227
|
+
return `${head} · 本地作答 local`;
|
|
228
|
+
case 'local-fallback':
|
|
229
|
+
return `${head} · 本地降级 local-fallback${fields.systemOneDetail ? `(${fields.systemOneDetail})` : ''}`;
|
|
230
|
+
case 'rejected':
|
|
231
|
+
return `${head} · 已拒绝 rejected${fields.systemOneDetail ? `(${fields.systemOneDetail})` : ''}`;
|
|
232
|
+
case 'unknown':
|
|
233
|
+
return `${head} · 来源未知 unknown`;
|
|
234
|
+
default:
|
|
235
|
+
return head;
|
|
236
|
+
}
|
|
237
|
+
}
|
|
238
|
+
//# sourceMappingURL=attribution.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"attribution.js","sourceRoot":"","sources":["../src/attribution.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AA4CH,8EAA8E;AAC9E,MAAM,CAAC,MAAM,oBAAoB,GAAG,MAAM,CAAC;AAE3C,6EAA6E;AAC7E,MAAM,CAAC,MAAM,4BAA4B,GAAG,cAAc,CAAC;AAE3D;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,YAAY,CAC1B,SAAkC,EAClC,eAA+D;IAE/D,IAAI,eAAe,KAAK,MAAM,IAAI,SAAS,CAAC,OAAO,KAAK,MAAM,EAAE,CAAC;QAC/D,OAAO,EAAE,cAAc,EAAE,oBAAoB,EAAE,cAAc,EAAE,IAAI,EAAE,CAAC;IACxE,CAAC;IACD,IAAI,SAAS,CAAC,YAAY,KAAK,SAAS,IAAI,SAAS,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;QAC3E,OAAO,EAAE,cAAc,EAAE,4BAA4B,EAAE,cAAc,EAAE,IAAI,EAAE,CAAC;IAChF,CAAC;IACD,OAAO,EAAE,cAAc,EAAE,SAAS,CAAC,MAAM,EAAE,cAAc,EAAE,SAAS,CAAC,KAAK,IAAI,IAAI,EAAE,CAAC;AACvF,CAAC;AAyBD;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,cAAc,CAC5B,QAAiB,EACjB,OAA2B,EAC3B,aAAsB,EACtB,SAAkB;IAElB,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QAC1B,6EAA6E;QAC7E,yEAAyE;QACzE,6EAA6E;QAC7E,4EAA4E;QAC5E,iCAAiC;QACjC,OAAO,QAAQ,IAAI,aAAa;YAC9B,CAAC,CAAC,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,EAAE,OAAO,EAAE;YAC/C,CAAC,CAAC,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;IAC9C,CAAC;IACD,IAAI,CAAC,QAAQ;QAAE,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,+BAA+B,EAAE,CAAC;IACtF,6EAA6E;IAC7E,4EAA4E;IAC5E,IAAI,SAAS;QAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,uCAAuC,EAAE,CAAC;IAC3F,IAAI,aAAa;QAAE,OAAO,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,EAAE,oDAAoD,EAAE,CAAC;IACrH,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC;AAC9B,CAAC;AAwCD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,UAAU,gBAAgB,CAAC,QAAwB;IACvD,MAAM,OAAO,GAAG,QAAQ,CAAC,SAAS,CAAC;IACnC,IAAI,QAAQ,CAAC,gBAAgB,KAAK,IAAI,EAAE,CAAC;QACvC,OAAO;YACL,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS;YACrC,GAAG,CAAC,OAAO;gBACT,CAAC,CAAC,EAAE;gBACJ,CAAC,CAAC,EAAE,MAAM,EAAE,mFAAmF,EAAE,CAAC;SACrG,CAAC;IACJ,CAAC;IACD,IAAI,QAAQ,CAAC,OAAO,KAAK,SAAS;QAAE,OAAO,cAAc,CAAC,KAAK,EAAE,QAAQ,CAAC,OAAO,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC;IACnG,IAAI,CAAC,QAAQ,CAAC,QAAQ;QAAE,OAAO,cAAc,CAAC,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC;IAChF,IAAI,OAAO;QAAE,OAAO,cAAc,CAAC,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC;IAEjE,4EAA4E;IAC5E,8EAA8E;IAC9E,0CAA0C;IAC1C,MAAM,MAAM,GAAG,QAAQ,CAAC,cAAc,IAAI,CAAC,CAAC;IAC5C,MAAM,KAAK,GAAG,QAAQ,CAAC,aAAa,CAAC;IACrC,MAAM,QAAQ,GACZ,KAAK,KAAK,SAAS,IAAI,KAAK,GAAG,MAAM;QACnC,CAAC,CAAC,CAAC,QAAQ,CAAC,iBAAiB,IAAI,+BAA+B,CAAC;QACjE,CAAC,CAAC,SAAS,CAAC;IAChB,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;QAC3B,2EAA2E;QAC3E,wEAAwE;QACxE,4EAA4E;QAC5E,2EAA2E;QAC3E,0CAA0C;QAC1C,OAAO,cAAc,CAAC,IAAI,EAAE,QAAQ,EAAE,QAAQ,CAAC,aAAa,KAAK,IAAI,EAAE,KAAK,CAAC,CAAC;IAChF,CAAC;IAED,IAAI,QAAQ,CAAC,cAAc,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QAC5D,OAAO;YACL,MAAM,EAAE,SAAS;YACjB,MAAM,EAAE,2FAA2F;SACpG,CAAC;IACJ,CAAC;IACD,OAAO,cAAc,CAAC,IAAI,EAAE,SAAS,EAAE,QAAQ,CAAC,aAAa,KAAK,IAAI,EAAE,KAAK,CAAC,CAAC;AACjF,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAAC,QAAsB,EAAE,OAAgD;IACpG,OAAO;QACL,cAAc,EAAE,QAAQ,CAAC,cAAc;QACvC,cAAc,EAAE,QAAQ,CAAC,cAAc;QACvC,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,GAAG,CAAC,OAAO,CAAC,MAAM,KAAK,SAAS,IAAI,OAAO,CAAC,MAAM,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC;KAC7F,CAAC;AACJ,CAAC;AAuBD;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAC,WAAwB;IACxD,OAAO;QACL,mBAAmB,EAAE,WAAW,CAAC,cAAc;QAC/C,cAAc,EAAE,WAAW,CAAC,cAAc;QAC1C,eAAe,EAAE,WAAW,CAAC,MAAM;QACnC,GAAG,CAAC,WAAW,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,eAAe,EAAE,WAAW,CAAC,MAAM,EAAE,CAAC;KACrF,CAAC;AACJ,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,mBAAmB,CAAC,MAAkC;IACpE,IAAI,OAAO,MAAM,CAAC,mBAAmB,KAAK,QAAQ,IAAI,MAAM,CAAC,mBAAmB,KAAK,EAAE;QAAE,OAAO,SAAS,CAAC;IAC1G,MAAM,KAAK,GAAG,MAAM,CAAC,cAAc,KAAK,IAAI,IAAI,MAAM,CAAC,cAAc,KAAK,SAAS,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,MAAM,CAAC,cAAc,CAAC;IAC3H,MAAM,IAAI,GAAG,GAAG,MAAM,CAAC,mBAAmB,WAAW,KAAK,EAAE,CAAC;IAC7D,QAAQ,MAAM,CAAC,eAAe,EAAE,CAAC;QAC/B,KAAK,OAAO;YACV,OAAO,GAAG,IAAI,eAAe,CAAC;QAChC,KAAK,gBAAgB;YACnB,OAAO,GAAG,IAAI,yBAAyB,MAAM,CAAC,eAAe,CAAC,CAAC,CAAC,IAAI,MAAM,CAAC,eAAe,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;QACvG,KAAK,UAAU;YACb,OAAO,GAAG,IAAI,kBAAkB,MAAM,CAAC,eAAe,CAAC,CAAC,CAAC,IAAI,MAAM,CAAC,eAAe,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;QAChG,KAAK,SAAS;YACZ,OAAO,GAAG,IAAI,iBAAiB,CAAC;QAClC;YACE,OAAO,IAAI,CAAC;IAChB,CAAC;AACH,CAAC","sourcesContent":["/**\n * Per-call provenance of one System One decision: which connection and which\n * requested model were in force **when the call was dispatched**, and where the\n * answer really came from.\n *\n * ## Why this module exists (g-068)\n *\n * A session switched the active System One profile three times and then to a\n * model that does not exist. Every call still answered, and the tool payloads\n * said nothing about the connection or the model, so the only honest sentence a\n * reader could write was \"no model is shown\". The reader cannot be expected to\n * reconstruct provenance from a payload that omits it, and the ledger used to\n * record a *backend class name* (`mock-heuristic-v1`, `system-one-jev`) that is\n * neither the connection the user named nor the model that was asked for.\n *\n * ## The four facts, and what each one may claim\n *\n * - `connectionName` — the name of the System One connection (the profile) that\n * was in force at dispatch. This is the one identity a human authored, so it\n * is what \"which connection answered?\" must answer. It is *not* the backend\n * class and *not* the main model the session itself is running on.\n * - `model` — the model id the runtime **requested** for this call. It is a\n * request, never an observation: a gateway may rewrite it, and this plugin\n * never sees what an upstream really served. Nothing here may ever be\n * presented as \"the model that answered\".\n * - `source` — where the answer came from, in states that must never be\n * collapsed: `remote`, `local` (this connection sends nothing),\n * `local-fallback` (a remote attempt happened and its failure was absorbed\n * locally) and `rejected` (the call failed and no answer was invented). A\n * fifth value, `unknown`, is what a call reports when nothing it could observe\n * *proves* any of the others — see {@link classifyEvidence}. It is a real\n * state, not a placeholder: a backend that publishes no failure record leaves\n * a settled call with no positive evidence that a request was answered, and\n * claiming `remote` there is exactly the falsehood this goal removes.\n * - `detail` — the reason a non-remote call is non-remote, kept so a reader can\n * tell \"no connection configured\" from \"the gateway refused the model\".\n *\n * ## Snapshot at dispatch, never re-read\n *\n * {@link callIdentity} is taken *before* the backend is awaited and carried\n * through the payload and the ledger entry. A profile switch, a concurrent\n * in-flight call, or a later history read therefore cannot restate an older\n * call: the answer keeps the identity it was asked under. That is the property\n * the `switch and in-flight` tests pin.\n *\n * ## What this module must never do\n *\n * It never reads or renders a key, an endpoint's credentials, or the main\n * model. `apiKeyEnv` is deliberately absent from {@link CallIdentity}: the\n * *name* of a variable is harmless but it is also not provenance, and a caller\n * that wants the connection's address/selector has the panel for that.\n *\n * @module dsh-reflex/attribution\n */\n\nimport type { ResolvedSystemOneConfig } from './config.js';\n\n/**\n * Where one answer came from.\n *\n * The states g-068 must keep apart, plus `unknown` for a caller that can prove\n * none of them:\n *\n * - `remote` — the connection was asked and answered;\n * - `local` — this connection sends no request at all (the in-process mock, or\n * an activation with no profile), so \"remote\" would be a lie;\n * - `local-fallback` — a remote attempt was made and **failed**, and the answer\n * was produced locally afterwards. This is the \"远端拒绝后本地降级\" case;\n * - `rejected` — the remote attempt failed and the call produced no decision of\n * its own (it threw), or produced only a fail-closed verdict.\n *\n * `local-fallback` and `rejected` are both failures of the remote attempt and\n * must never be rendered as a remote success.\n */\nexport type CallSource = 'remote' | 'local' | 'local-fallback' | 'rejected' | 'unknown';\n\n/** Provenance of one decision call, as taken at dispatch. */\nexport interface CallIdentity {\n /**\n * Name of the System One connection in force at dispatch.\n *\n * The active profile's name, or one of the two synthetic names this module\n * defines when no profile exists: `mock` for a deployment that explicitly\n * chose the in-process implementation, `unconfigured` for an activation that\n * has no connection at all. Never the backend class name.\n */\n readonly connectionName: string;\n /**\n * The model id this call **requested**, or `null` when the connection names\n * none (nothing was sent, or the backend's own default applies).\n *\n * A request, never an observation: this plugin cannot see whether an upstream\n * served, rewrote, or ignored it. Renderers must keep that wording.\n */\n readonly requestedModel: string | null;\n}\n\n/** The connection name used when the deployment explicitly chose the mock. */\nexport const MOCK_CONNECTION_NAME = 'mock';\n\n/** The connection name used when the activation has no connection at all. */\nexport const UNCONFIGURED_CONNECTION_NAME = 'unconfigured';\n\n/**\n * Read the identity of the connection an activation would use right now.\n *\n * Pure and synchronous on purpose: the caller takes it at dispatch, before any\n * request leaves, so what it reports is the connection the call was *asked*\n * under rather than whatever the live config says when the answer arrives.\n *\n * The order matters and mirrors {@link createBackend}: an explicit `mock`\n * outranks the \"no active profile\" rule (the mock never uses a profile), and an\n * `unconfigured` connection is named as such rather than by the profile the\n * document happens to carry.\n * @param systemOne - the resolved connection block currently in force.\n * @param backendSelector - the deployment's backend selector (`auto` when unauthored).\n * @returns the identity to carry through the payload and the ledger entry.\n */\nexport function callIdentity(\n systemOne: ResolvedSystemOneConfig,\n backendSelector: ResolvedSystemOneConfig['backend'] | undefined\n): CallIdentity {\n if (backendSelector === 'mock' || systemOne.backend === 'mock') {\n return { connectionName: MOCK_CONNECTION_NAME, requestedModel: null };\n }\n if (systemOne.unconfigured !== undefined || systemOne.active === undefined) {\n return { connectionName: UNCONFIGURED_CONNECTION_NAME, requestedModel: null };\n }\n return { connectionName: systemOne.active, requestedModel: systemOne.model ?? null };\n}\n\n/** One call's provenance as it appears in a tool payload. */\nexport interface Attribution {\n /**\n * Name of the System One connection the call used.\n *\n * The profile the user activated — not the backend class, and not the main\n * model this session runs on.\n */\n connectionName: string;\n /**\n * The model id this call requested from that connection; `null` when the\n * connection names none.\n *\n * A request, not an observation: whether an upstream served or rewrote it is\n * unknown to this plugin.\n */\n requestedModel: string | null;\n /** Where the answer came from (see {@link CallSource}). */\n source: CallSource;\n /** Why the source is not `remote`; absent exactly when `source` is `remote`. */\n detail?: string;\n}\n\n/**\n * Classify one settled attempt into a {@link CallSource}.\n *\n * `answered` is the only question asked of the outcome: a call that produced a\n * decision was answered, whatever path produced it. The reason decides between\n * a remote answer and a local one, because a locally absorbed failure must stay\n * distinguishable from a gateway answer.\n * @param answered - whether the call produced a decision at all.\n * @param failure - the absorbed failure, when one happened.\n * @param localFallback - whether the answered value was produced locally *after*\n * a remote attempt failed (rather than by a local-only connection).\n * @param localOnly - whether this connection makes no request at all.\n * @returns the source, and the detail for a non-remote one.\n */\nexport function classifySource(\n answered: boolean,\n failure: string | undefined,\n localFallback: boolean,\n localOnly: boolean\n): { source: CallSource; detail?: string } {\n if (failure !== undefined) {\n // A remote attempt happened and its request failed. What the caller did with\n // that failure is the distinction the goal exists to preserve: an answer\n // produced *locally afterwards* is a local fallback (a remote rejection that\n // was absorbed), while a call with no answer is a rejection. Neither may be\n // described as a remote success.\n return answered && localFallback\n ? { source: 'local-fallback', detail: failure }\n : { source: 'rejected', detail: failure };\n }\n if (!answered) return { source: 'rejected', detail: 'the call produced no decision' };\n // A connection that sends nothing is local by construction, not by fallback:\n // the two read differently in a ledger and mean different things to a user.\n if (localOnly) return { source: 'local', detail: `no request is sent by this connection` };\n if (localFallback) return { source: 'local-fallback', detail: 'the answer was produced locally, not by System One' };\n return { source: 'remote' };\n}\n\n/**\n * What one dispatch could prove about where its answer came from.\n *\n * Every field is something the runtime *observed*; none is inferred from a\n * request id or from the settings in force at read time.\n */\nexport interface SourceEvidence {\n /** Whether the call produced a decision at all. */\n readonly answered: boolean;\n /** The thrown failure, when the call threw. */\n readonly failure?: string;\n /** Whether the answered value was produced locally after a remote failure. */\n readonly localFallback?: boolean;\n /** Whether this connection sends no request at all. */\n readonly localOnly: boolean;\n /**\n * Whether the backend exposes a failure record this module may read.\n *\n * Only `JevDecisionBackend` has one. The vLLM logits backend has no\n * `health()`, and its services absorb a gateway failure into a fail-closed\n * verdict the same way the JEV one does — so without a record, a settled call\n * here has **no positive evidence** that a request was made and answered.\n */\n readonly healthReadable: boolean;\n /** `consecutiveFailures` before the call, when the record is readable. */\n readonly failuresBefore?: number;\n /** `consecutiveFailures` after the call, when the record is readable. */\n readonly failuresAfter?: number;\n /** The backend's reason for its most recent failure, when readable. */\n readonly lastFailureReason?: string;\n /**\n * Whether the ledger entry this call produced arrived **after** the call\n * settled — in which case the source written on the entry cannot be trusted\n * to be this call's.\n */\n readonly entryArrivedLate?: boolean;\n}\n\n/**\n * Classify a settled attempt from evidence, preferring `unknown` to a claim.\n *\n * This is {@link classifySource} with the one question the first version got\n * wrong added: a call that resolved and *looked* remote may have had its\n * request rejected and its failure absorbed — by the gate, or by a prune that\n * fell back — and claiming `remote` for it is the precise falsehood g-068\n * forbids. Three states are therefore never guessed:\n *\n * - a **late entry** means this call's provenance could not be tied to the\n * entry that carried it, so the source is `unknown` (the ledger line itself\n * also says `unknown`; the two surfaces agree);\n * - a connection that sends nothing is `local` by construction, without asking;\n * - a **settled, non-local call on a backend with no readable failure record**\n * has no positive evidence for `remote`, so it is `unknown`. The fail-closed\n * verdict the caller still receives is unchanged; only the claim about its\n * provenance is withdrawn.\n *\n * Everything the first version handled keeps its old answer: a thrown call is\n * `rejected`, a local answer after a failure is `local-fallback`, and a local\n * path that is reported by the service itself stays `local`/`local-fallback`.\n * @param evidence - the facts the dispatch observed.\n * @returns the source, and the detail for a non-remote one.\n */\nexport function classifyEvidence(evidence: SourceEvidence): { source: CallSource; detail?: string } {\n const isLocal = evidence.localOnly;\n if (evidence.entryArrivedLate === true) {\n return {\n source: isLocal ? 'local' : 'unknown',\n ...(isLocal\n ? {}\n : { detail: 'the ledger entry for this call could not be tied to it, so its source is unproven' })\n };\n }\n if (evidence.failure !== undefined) return classifySource(false, evidence.failure, false, isLocal);\n if (!evidence.answered) return classifySource(false, undefined, false, isLocal);\n if (isLocal) return classifySource(true, undefined, false, true);\n\n // A readable record proves a failure when the failure count rose across the\n // call. It proves a *success* only when the backend has one and did not rise;\n // without one, `remote` would be a guess.\n const before = evidence.failuresBefore ?? 0;\n const after = evidence.failuresAfter;\n const absorbed =\n after !== undefined && after > before\n ? (evidence.lastFailureReason ?? 'the System One request failed')\n : undefined;\n if (absorbed !== undefined) {\n // A failure the service absorbed is a rejection unless the caller says the\n // answered value was produced *locally* afterwards. A gate that turns a\n // gateway failure into a fail-closed `escalate` verdict made no decision of\n // its own, so it is `rejected` — not `local-fallback`, which would claim a\n // local judgment replaced the failed one.\n return classifySource(true, absorbed, evidence.localFallback === true, false);\n }\n\n if (evidence.healthReadable !== true || after === undefined) {\n return {\n source: 'unknown',\n detail: 'this connection exposes no failure record, so no evidence proves the request was answered'\n };\n }\n return classifySource(true, undefined, evidence.localFallback === true, false);\n}\n\n/**\n * Compose the payload fields one call reports.\n * @param identity - the identity taken at dispatch.\n * @param outcome - the classified source and detail.\n * @returns the attribution object to spread into a tool payload or lead a ledger entry.\n */\nexport function attributionOf(identity: CallIdentity, outcome: { source: CallSource; detail?: string }): Attribution {\n return {\n connectionName: identity.connectionName,\n requestedModel: identity.requestedModel,\n source: outcome.source,\n ...(outcome.detail === undefined || outcome.detail === '' ? {} : { detail: outcome.detail })\n };\n}\n\n/**\n * The ledger's view of one call's provenance.\n *\n * Flat and prefixed (`systemOneConnection`, `systemOneModel`, `systemOneSource`)\n * rather than nested, so an existing JSONL reader that greps a single line can\n * pick the facts out without knowing the nesting, and so `backend` keeps its\n * historical meaning (\"which implementation class answered\") beside them. The\n * three are the facts g-068 requires the ledger to carry; none of them is ever\n * inferred from a request id, and `systemOneModel` is the *requested* id.\n */\nexport interface LedgerAttribution {\n /** Connection name in force at dispatch (see {@link CallIdentity.connectionName}). */\n systemOneConnection: string;\n /** Model id the call requested, `null` when the connection names none. */\n systemOneModel: string | null;\n /** Where the answer came from. */\n systemOneSource: CallSource;\n /** Why the source is not `remote`; absent when it is. */\n systemOneDetail?: string;\n}\n\n/**\n * Project an attribution onto the ledger's flat fields.\n * @param attribution - the call's attribution.\n * @returns the flat ledger fields.\n */\nexport function ledgerAttribution(attribution: Attribution): LedgerAttribution {\n return {\n systemOneConnection: attribution.connectionName,\n systemOneModel: attribution.requestedModel,\n systemOneSource: attribution.source,\n ...(attribution.detail === undefined ? {} : { systemOneDetail: attribution.detail })\n };\n}\n\n/**\n * Render one attribution as the single line `/reflex-ledger` prints.\n *\n * Bilingual and compact: the connection name, the requested model (marked as a\n * request), and — for a non-remote call — the source with its reason. A `remote`\n * call prints no source word, because \"answered by the connection as asked\" is\n * the only reading that needs no warning; a local fallback or a rejection always\n * says so.\n * @param fields - the flat ledger fields of one entry.\n * @returns the line segment, or `undefined` for an entry that predates g-068.\n */\nexport function describeAttribution(fields: Partial<LedgerAttribution>): string | undefined {\n if (typeof fields.systemOneConnection !== 'string' || fields.systemOneConnection === '') return undefined;\n const model = fields.systemOneModel === null || fields.systemOneModel === undefined ? '无模型 / none' : fields.systemOneModel;\n const head = `${fields.systemOneConnection} · 请求模型 ${model}`;\n switch (fields.systemOneSource) {\n case 'local':\n return `${head} · 本地作答 local`;\n case 'local-fallback':\n return `${head} · 本地降级 local-fallback${fields.systemOneDetail ? `(${fields.systemOneDetail})` : ''}`;\n case 'rejected':\n return `${head} · 已拒绝 rejected${fields.systemOneDetail ? `(${fields.systemOneDetail})` : ''}`;\n case 'unknown':\n return `${head} · 来源未知 unknown`;\n default:\n return head;\n }\n}\n"]}
|