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.
Files changed (124) hide show
  1. package/README.md +20 -6
  2. package/client.js +3511 -185
  3. package/dist/attribution.d.ts +266 -0
  4. package/dist/attribution.js +238 -0
  5. package/dist/attribution.js.map +1 -0
  6. package/dist/bridge.d.ts +311 -13
  7. package/dist/bridge.js +714 -42
  8. package/dist/bridge.js.map +1 -1
  9. package/dist/client-bundle.js +4 -1
  10. package/dist/client-bundle.js.map +1 -1
  11. package/dist/command.js +10 -0
  12. package/dist/command.js.map +1 -1
  13. package/dist/config.d.ts +530 -22
  14. package/dist/config.js +808 -27
  15. package/dist/config.js.map +1 -1
  16. package/dist/delegation-dispatch.d.ts +132 -0
  17. package/dist/delegation-dispatch.js +186 -0
  18. package/dist/delegation-dispatch.js.map +1 -0
  19. package/dist/delegation-health.d.ts +131 -0
  20. package/dist/delegation-health.js +97 -0
  21. package/dist/delegation-health.js.map +1 -0
  22. package/dist/delegation.d.ts +148 -0
  23. package/dist/delegation.js +186 -0
  24. package/dist/delegation.js.map +1 -0
  25. package/dist/effort-delegation.d.ts +144 -0
  26. package/dist/effort-delegation.js +280 -0
  27. package/dist/effort-delegation.js.map +1 -0
  28. package/dist/effort.d.ts +141 -0
  29. package/dist/effort.js +251 -9
  30. package/dist/effort.js.map +1 -1
  31. package/dist/host-patch.d.ts +156 -0
  32. package/dist/host-patch.js +534 -0
  33. package/dist/host-patch.js.map +1 -0
  34. package/dist/index.d.ts +12 -3
  35. package/dist/index.js +99 -7
  36. package/dist/index.js.map +1 -1
  37. package/dist/interventions.d.ts +98 -373
  38. package/dist/interventions.js +442 -1702
  39. package/dist/interventions.js.map +1 -1
  40. package/dist/panel-api.d.ts +328 -4
  41. package/dist/panel-api.js +322 -15
  42. package/dist/panel-api.js.map +1 -1
  43. package/dist/panel-mount.d.ts +81 -22
  44. package/dist/panel-mount.js +228 -7
  45. package/dist/panel-mount.js.map +1 -1
  46. package/dist/routing.d.ts +23 -18
  47. package/dist/routing.js +471 -153
  48. package/dist/routing.js.map +1 -1
  49. package/dist/session-audit.d.ts +70 -0
  50. package/dist/session-audit.js +73 -0
  51. package/dist/session-audit.js.map +1 -1
  52. package/dist/systemone-probe.d.ts +114 -0
  53. package/dist/systemone-probe.js +383 -0
  54. package/dist/systemone-probe.js.map +1 -0
  55. package/dist/testing.d.ts +212 -7
  56. package/dist/testing.js +333 -27
  57. package/dist/testing.js.map +1 -1
  58. package/dist/tools.d.ts +109 -3
  59. package/dist/tools.js +103 -4
  60. package/dist/tools.js.map +1 -1
  61. package/dist/unconfigured-backend.d.ts +72 -0
  62. package/dist/unconfigured-backend.js +94 -0
  63. package/dist/unconfigured-backend.js.map +1 -0
  64. package/dist/vendor/harness-reflex/backend/factory.d.ts +31 -1
  65. package/dist/vendor/harness-reflex/backend/factory.js +18 -3
  66. package/dist/vendor/harness-reflex/backend/factory.js.map +1 -1
  67. package/dist/vendor/harness-reflex/backend/jev.d.ts +20 -0
  68. package/dist/vendor/harness-reflex/backend/jev.js +11 -4
  69. package/dist/vendor/harness-reflex/backend/jev.js.map +1 -1
  70. package/dist/vendor/harness-reflex/backend/simple-jev.d.ts +16 -0
  71. package/dist/vendor/harness-reflex/backend/simple-jev.js +17 -6
  72. package/dist/vendor/harness-reflex/backend/simple-jev.js.map +1 -1
  73. package/dist/vendor/harness-reflex/core/closing.d.ts +90 -0
  74. package/dist/vendor/harness-reflex/core/closing.js +111 -0
  75. package/dist/vendor/harness-reflex/core/closing.js.map +1 -0
  76. package/dist/vendor/harness-reflex/core/evidence.d.ts +119 -0
  77. package/dist/vendor/harness-reflex/core/evidence.js +209 -0
  78. package/dist/vendor/harness-reflex/core/evidence.js.map +1 -0
  79. package/dist/vendor/harness-reflex/core/judge.d.ts +221 -0
  80. package/dist/vendor/harness-reflex/core/judge.js +251 -0
  81. package/dist/vendor/harness-reflex/core/judge.js.map +1 -0
  82. package/dist/vendor/harness-reflex/core/orchestrate-closing.d.ts +237 -0
  83. package/dist/vendor/harness-reflex/core/orchestrate-closing.js +250 -0
  84. package/dist/vendor/harness-reflex/core/orchestrate-closing.js.map +1 -0
  85. package/dist/vendor/harness-reflex/core/orchestrate-correction.d.ts +209 -0
  86. package/dist/vendor/harness-reflex/core/orchestrate-correction.js +141 -0
  87. package/dist/vendor/harness-reflex/core/orchestrate-correction.js.map +1 -0
  88. package/dist/vendor/harness-reflex/core/orchestrate-host.d.ts +225 -0
  89. package/dist/vendor/harness-reflex/core/orchestrate-host.js +80 -0
  90. package/dist/vendor/harness-reflex/core/orchestrate-host.js.map +1 -0
  91. package/dist/vendor/harness-reflex/core/orchestrate-stagnation.d.ts +259 -0
  92. package/dist/vendor/harness-reflex/core/orchestrate-stagnation.js +270 -0
  93. package/dist/vendor/harness-reflex/core/orchestrate-stagnation.js.map +1 -0
  94. package/dist/vendor/harness-reflex/core/orchestrate.d.ts +357 -0
  95. package/dist/vendor/harness-reflex/core/orchestrate.js +418 -0
  96. package/dist/vendor/harness-reflex/core/orchestrate.js.map +1 -0
  97. package/dist/vendor/harness-reflex/core/policy.d.ts +122 -0
  98. package/dist/vendor/harness-reflex/core/policy.js +102 -0
  99. package/dist/vendor/harness-reflex/core/policy.js.map +1 -0
  100. package/dist/vendor/harness-reflex/core/prune-plan.d.ts +141 -0
  101. package/dist/vendor/harness-reflex/core/prune-plan.js +390 -0
  102. package/dist/vendor/harness-reflex/core/prune-plan.js.map +1 -0
  103. package/dist/vendor/harness-reflex/core/text.d.ts +36 -0
  104. package/dist/vendor/harness-reflex/core/text.js +66 -0
  105. package/dist/vendor/harness-reflex/core/text.js.map +1 -0
  106. package/dist/vendor/harness-reflex/ports/audit.d.ts +18 -0
  107. package/dist/vendor/harness-reflex/ports/audit.js +11 -0
  108. package/dist/vendor/harness-reflex/ports/audit.js.map +1 -0
  109. package/dist/vendor/harness-reflex/ports/clock.d.ts +14 -0
  110. package/dist/vendor/harness-reflex/ports/clock.js +11 -0
  111. package/dist/vendor/harness-reflex/ports/clock.js.map +1 -0
  112. package/dist/vendor/harness-reflex/ports/decision.d.ts +75 -0
  113. package/dist/vendor/harness-reflex/ports/decision.js +2 -0
  114. package/dist/vendor/harness-reflex/ports/decision.js.map +1 -0
  115. package/dist/vendor/harness-reflex/ports/index.d.ts +14 -0
  116. package/dist/vendor/harness-reflex/ports/index.js +2 -0
  117. package/dist/vendor/harness-reflex/ports/index.js.map +1 -0
  118. package/dist/vendor/harness-reflex/ports/log.d.ts +22 -0
  119. package/dist/vendor/harness-reflex/ports/log.js +12 -0
  120. package/dist/vendor/harness-reflex/ports/log.js.map +1 -0
  121. package/dist/vendor/harness-reflex/ports/state.d.ts +46 -0
  122. package/dist/vendor/harness-reflex/ports/state.js +13 -0
  123. package/dist/vendor/harness-reflex/ports/state.js.map +1 -0
  124. 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"]}