@dsh-cc/tool-search 0.9.4 → 0.9.5

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.
@@ -0,0 +1,296 @@
1
+ /**
2
+ * The in-process judgment cache of S1-05 tool discovery: a bounded LRU with
3
+ * lazy TTL expiry, plus same-key request coalescing with independent caller
4
+ * cancellation.
5
+ *
6
+ * Design: `docs/plans/2026-11-02-systemone-05-tool-discovery.md`
7
+ * § "Lifecycle, cache, and failure handling" and § "Settings". The protocol
8
+ * this file implements is the one shared with S1-06/S1-11/S1-12 and verified in
9
+ * `specs/tla/decision-gate-coalescing`:
10
+ *
11
+ * - **cache-then-coalesce**: a completed judgment is stored BEFORE waiters are
12
+ * woken, and an in-flight run is joined rather than duplicated;
13
+ * - **only complete answers are cached**: a rejected run (timeout, transport
14
+ * error, missing route, partial batch) and an abandoned run (every waiter
15
+ * left) store nothing;
16
+ * - **per-caller independent cancellation**: each waiter's own `AbortSignal`
17
+ * ends only that waiter's wait — nothing is published on its behalf — while
18
+ * the shared request keeps running for the others;
19
+ * - **last waiter aborts the request**: the underlying factory's signal fires
20
+ * only when the refcount drops to zero;
21
+ * - **post-await revalidation** stays with the caller (design step 9): this
22
+ * layer only guarantees that a run whose catalog/admission/identity/threshold
23
+ * inputs changed is a DIFFERENT key, so a stale judgment is never reused.
24
+ *
25
+ * The model's invariants map onto this file as `AbortOnlyWhenAllCancelled` and
26
+ * `SettledHoldsSlot` (the refcounted {@link Flight}), `CacheCompleteOnly` (a
27
+ * failed or abandoned run stores nothing), and `NoConsumeAfterCancel` (a
28
+ * cancelled waiter resolves `cancelled` and publishes nothing).
29
+ *
30
+ * There is no persistence, no background sweep, and no timer: an expired entry
31
+ * is discovered at read time and treated as absent.
32
+ *
33
+ * @module @dsh-cc/tool-search/discovery-cache
34
+ */
35
+ /**
36
+ * Key-format version. Bumping it retires every previously stored entry without
37
+ * having to reason about collisions with an older field order.
38
+ */
39
+ export const DISCOVERY_CACHE_KEY_VERSION = 'tool-discovery-key-v1';
40
+ /**
41
+ * Build the cache key for one discovery transaction.
42
+ *
43
+ * The fields are serialized in a fixed order as a JSON array, so a value can
44
+ * never bleed into the next slot (a length-prefixed/escaped join would have to
45
+ * re-derive that invariant). The query is trimmed first: `" x "` and `"x"`
46
+ * describe the same judgment and must share a key.
47
+ * @param parts - the transaction identity.
48
+ * @returns an opaque, deterministic key string.
49
+ */
50
+ export function buildDiscoveryCacheKey(parts) {
51
+ const { route, thresholds } = parts;
52
+ return JSON.stringify([
53
+ DISCOVERY_CACHE_KEY_VERSION,
54
+ parts.project,
55
+ parts.session,
56
+ parts.agent,
57
+ parts.originSeq,
58
+ parts.query.trim(),
59
+ parts.catalogHash,
60
+ parts.admissionHash,
61
+ route.provider,
62
+ route.model,
63
+ route.revision,
64
+ route.perRequestTokens,
65
+ route.perQuestionTokens,
66
+ route.maxQuestions,
67
+ route.maxOutputTokens,
68
+ parts.questionVersion,
69
+ parts.policyVersion,
70
+ thresholds.timeoutMs,
71
+ thresholds.maxInputTokens,
72
+ thresholds.maxCandidates,
73
+ thresholds.batchSize,
74
+ thresholds.maxQueryChars,
75
+ thresholds.maxMetadataChars,
76
+ thresholds.minRelevanceIndex,
77
+ thresholds.minDirectFit,
78
+ thresholds.maxActivations,
79
+ ]);
80
+ }
81
+ /**
82
+ * Default cacheability: a discriminated judgment is stored only when it is a
83
+ * validated `selected` answer (design § "Lifecycle, cache, and failure
84
+ * handling"). A non-discriminated value has no verdict to second-guess and is
85
+ * stored. Note this is a shape test, not the validation itself: the judgment
86
+ * layer must mint `kind: 'selected'` only after full validation.
87
+ */
88
+ function defaultCacheable(value) {
89
+ if (value === null || typeof value !== 'object' || !('kind' in value))
90
+ return true;
91
+ return value.kind === 'selected';
92
+ }
93
+ /**
94
+ * In-process LRU cache with TTL and refcounted same-key coalescing.
95
+ *
96
+ * One instance per plugin fiber (design § "Lifecycle, cache, and failure
97
+ * handling": plugin unload aborts its requests and clears the cache — call
98
+ * {@link DiscoveryCache.clear} from the unload path). Storage is a `Map`, whose
99
+ * iteration order is the LRU order: a read re-inserts the entry at the MRU end,
100
+ * a write beyond `maxEntries` evicts from the front.
101
+ */
102
+ export class DiscoveryCache {
103
+ entries = new Map();
104
+ flights = new Map();
105
+ maxEntries;
106
+ ttlMs;
107
+ cacheable;
108
+ now;
109
+ constructor(options) {
110
+ this.maxEntries = Math.max(0, Math.trunc(options.maxEntries));
111
+ this.ttlMs = options.ttlMs;
112
+ this.cacheable = options.cacheable ?? defaultCacheable;
113
+ this.now = options.now ?? Date.now;
114
+ }
115
+ /** Stored entries currently held (expired ones are dropped as they are read). */
116
+ get size() {
117
+ return this.entries.size;
118
+ }
119
+ /** Keys with an in-flight shared run. */
120
+ get pending() {
121
+ return this.flights.size;
122
+ }
123
+ /**
124
+ * Resolve one discovery transaction, reusing a cached judgment or joining the
125
+ * in-flight run for the same key.
126
+ *
127
+ * - a warm entry is returned without invoking `factory`;
128
+ * - concurrent callers with the same key share ONE `factory` invocation;
129
+ * - `signal` cancels only THIS caller's wait (resolving `cancelled`, so the
130
+ * caller activates nothing); the shared request is aborted only when the
131
+ * last waiter's signal aborts;
132
+ * - a factory rejection (timeout, transport error, partial batch) is
133
+ * propagated to every remaining waiter and caches nothing.
134
+ * @param key - the key from {@link buildDiscoveryCacheKey}.
135
+ * @param factory - performs the judgment; receives the shared abort signal.
136
+ * @param signal - the calling transaction's own cancellation signal.
137
+ * @returns the judgment, or `cancelled` when this caller left.
138
+ */
139
+ async run(key, factory, signal) {
140
+ const cached = this.read(key);
141
+ if (cached !== undefined)
142
+ return { status: 'ok', value: cached.value };
143
+ if (signal?.aborted === true)
144
+ return { status: 'cancelled' };
145
+ const flight = this.flightOf(key, factory);
146
+ return this.awaitFlight(key, flight, signal);
147
+ }
148
+ /**
149
+ * Drop every stored entry and abort every in-flight run, resolving its
150
+ * waiters as cancelled. This is the plugin-unload / rollback hook (design
151
+ * § "Lifecycle, cache, and failure handling" and § "Release gates and
152
+ * rollback").
153
+ */
154
+ clear() {
155
+ this.entries.clear();
156
+ for (const [key, flight] of [...this.flights]) {
157
+ this.flights.delete(key);
158
+ flight.settled = true;
159
+ if (!flight.controller.signal.aborted)
160
+ flight.controller.abort();
161
+ for (const waiter of [...flight.waiters]) {
162
+ flight.waiters.delete(waiter);
163
+ waiter.resolve({ status: 'cancelled' });
164
+ }
165
+ }
166
+ }
167
+ /** A warm, unexpired entry, promoted to the MRU end. */
168
+ read(key) {
169
+ const entry = this.entries.get(key);
170
+ if (entry === undefined)
171
+ return undefined;
172
+ // Lazy expiry: no timer, no sweep — an expired entry is absent on read.
173
+ if (this.ttlMs <= 0 || this.now() - entry.storedAt >= this.ttlMs) {
174
+ this.entries.delete(key);
175
+ return undefined;
176
+ }
177
+ this.entries.delete(key);
178
+ this.entries.set(key, entry);
179
+ return entry;
180
+ }
181
+ /** Store one completed judgment, evicting the least recently used entry. */
182
+ store(key, value) {
183
+ if (this.maxEntries <= 0)
184
+ return;
185
+ if (!this.cacheable(value))
186
+ return;
187
+ this.entries.delete(key);
188
+ this.entries.set(key, { value, storedAt: this.now() });
189
+ while (this.entries.size > this.maxEntries) {
190
+ const oldest = this.entries.keys().next();
191
+ if (oldest.done === true)
192
+ return;
193
+ this.entries.delete(oldest.value);
194
+ }
195
+ }
196
+ /** The flight for a key, starting one when this caller is the first. */
197
+ flightOf(key, factory) {
198
+ const existing = this.flights.get(key);
199
+ if (existing !== undefined)
200
+ return existing;
201
+ const flight = { controller: new AbortController(), waiters: new Set(), settled: false };
202
+ this.flights.set(key, flight);
203
+ this.start(key, flight, factory);
204
+ return flight;
205
+ }
206
+ /** Invoke the factory once and settle the flight when it finishes. */
207
+ start(key, flight, factory) {
208
+ let started;
209
+ try {
210
+ started = factory(flight.controller.signal);
211
+ }
212
+ catch (error) {
213
+ // A factory that throws synchronously is a failed run like any other.
214
+ started = Promise.reject(error);
215
+ }
216
+ // The rejection is always handled here, so an abandoned run whose factory
217
+ // aborts and then rejects never surfaces as an unhandled rejection.
218
+ void started.then(value => this.complete(key, flight, value), error => this.fail(key, flight, error));
219
+ }
220
+ /** Store (when allowed), then wake every remaining waiter with the value. */
221
+ complete(key, flight, value) {
222
+ this.detach(key, flight);
223
+ flight.settled = true;
224
+ // A run that lost its last waiter was aborted; it is never cached, even if
225
+ // the factory resolved anyway.
226
+ if (!flight.controller.signal.aborted)
227
+ this.store(key, value);
228
+ for (const waiter of [...flight.waiters]) {
229
+ flight.waiters.delete(waiter);
230
+ waiter.resolve({ status: 'ok', value });
231
+ }
232
+ }
233
+ /** Propagate a failed run to every remaining waiter; nothing is cached. */
234
+ fail(key, flight, error) {
235
+ this.detach(key, flight);
236
+ flight.settled = true;
237
+ for (const waiter of [...flight.waiters]) {
238
+ flight.waiters.delete(waiter);
239
+ waiter.reject(error);
240
+ }
241
+ }
242
+ /** Forget the flight for a key, leaving a newer one in place if it replaced this. */
243
+ detach(key, flight) {
244
+ if (this.flights.get(key) === flight)
245
+ this.flights.delete(key);
246
+ }
247
+ /** Remove one waiter, aborting the shared request when it was the last. */
248
+ leave(key, flight, waiter) {
249
+ flight.waiters.delete(waiter);
250
+ if (flight.settled || flight.waiters.size > 0)
251
+ return;
252
+ // Last waiter gone: nothing can publish this run, so abort it and stop
253
+ // coalescing onto it. The late settlement above caches nothing.
254
+ this.detach(key, flight);
255
+ if (!flight.controller.signal.aborted)
256
+ flight.controller.abort();
257
+ }
258
+ /** Register one caller as a waiter of a flight. */
259
+ awaitFlight(key, flight, signal) {
260
+ return new Promise((resolve, reject) => {
261
+ let settled = false;
262
+ const unwatch = () => signal?.removeEventListener('abort', onAbort);
263
+ const onAbort = () => {
264
+ if (settled)
265
+ return;
266
+ settled = true;
267
+ // THIS caller leaves; the judgment continues for the other waiters.
268
+ this.leave(key, flight, waiter);
269
+ resolve({ status: 'cancelled' });
270
+ };
271
+ const waiter = {
272
+ resolve: (outcome) => {
273
+ if (settled)
274
+ return;
275
+ settled = true;
276
+ unwatch();
277
+ resolve(outcome);
278
+ },
279
+ reject: (error) => {
280
+ if (settled)
281
+ return;
282
+ settled = true;
283
+ unwatch();
284
+ reject(error);
285
+ },
286
+ };
287
+ signal?.addEventListener('abort', onAbort, { once: true });
288
+ flight.waiters.add(waiter);
289
+ // The signal may have aborted between the pre-check and the listener
290
+ // registration; an already-aborted signal never fires the event.
291
+ if (signal?.aborted === true)
292
+ onAbort();
293
+ });
294
+ }
295
+ }
296
+ //# sourceMappingURL=discovery-cache.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"discovery-cache.js","sourceRoot":"","sources":["../src/discovery-cache.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,144 @@
1
+ /**
2
+ * The structural boundary between tool discovery and S1-02's decision runtime:
3
+ * the request/response faces it consumes, the host resolver seam, and the two
4
+ * snapshot digests that pin a judgment to a catalog and an admission set.
5
+ *
6
+ * Design: `docs/plans/2026-11-02-systemone-05-tool-discovery.md`
7
+ * § "File responsibilities" (the runner comes from the optional
8
+ * `ctx.systemoneDecisions` service; re-read the identity after every await and
9
+ * compare all fields), § "Inputs, questions, and output", § "Lifecycle, cache,
10
+ * and failure handling" (what the cache key pins).
11
+ *
12
+ * These interfaces are declared STRUCTURALLY — exactly as `discovery.ts`
13
+ * declares the question and answer shapes — so `@dsh-cc/tool-search` never takes
14
+ * a dependency on the SystemOne client: the host passes its real
15
+ * `BoundDecisionRunner`/`DecisionRun` through these seams unchanged.
16
+ *
17
+ * @module @dsh-cc/tool-search/discovery-contract
18
+ */
19
+ import type { DeferredEntry, DiscoveryAnswer, DiscoveryCandidate, DiscoveryQuestion, DiscoveryRouteIdentity, DiscoverySettings } from './discovery.ts';
20
+ import type { DiscoveryThresholds } from './discovery-cache.ts';
21
+ /** The actor a judgment is bound to: structurally an `Agent`, opaque here. */
22
+ export type DiscoveryActor = object;
23
+ /**
24
+ * The metering scope S1-02 binds to an actor: the host resolves project,
25
+ * session and agent, and `originSeq` is the persisted session watermark —
26
+ * never `events.length` (§ "Inputs, questions, and output").
27
+ */
28
+ export interface DiscoveryScope {
29
+ readonly projectKey: string;
30
+ readonly sessionId: string;
31
+ readonly agentId: string;
32
+ readonly originSeq: number;
33
+ }
34
+ /** One parsed answer map, keyed by question key. */
35
+ export type DiscoveryAnswerMap = Readonly<Record<string, DiscoveryAnswer | undefined>>;
36
+ /** The closed unavailable reasons of a runner decision (S1-02 contract). */
37
+ export type DiscoveryUnavailableReason = 'unconfigured' | 'budget' | 'timeout' | 'cancelled' | 'malformed' | 'error';
38
+ /** One runner response, structurally S1-02's `DecisionRun`. */
39
+ export type DiscoveryDecisionRun = {
40
+ readonly status: 'answered';
41
+ readonly answers: DiscoveryAnswerMap;
42
+ readonly decisionId?: string;
43
+ } | {
44
+ readonly status: 'unavailable';
45
+ readonly reason: DiscoveryUnavailableReason;
46
+ readonly decisionId?: string;
47
+ };
48
+ /**
49
+ * The one request this layer sends, structurally S1-02's `DecisionRequest`.
50
+ * `state` carries ONLY the query and this batch's candidate metadata — no tool
51
+ * callbacks, credentials, parameter schemas or message history.
52
+ */
53
+ export interface DiscoveryDecisionRequest {
54
+ readonly feature: 'tool-discovery';
55
+ readonly mode: 'shadow' | 'active';
56
+ readonly routeAlias: string;
57
+ readonly questionVersion: string;
58
+ readonly policyVersion: string;
59
+ readonly scope: DiscoveryScope;
60
+ readonly state: unknown;
61
+ readonly questions: Record<string, DiscoveryQuestion>;
62
+ readonly timeoutMs: number;
63
+ readonly maxInputTokens: number;
64
+ readonly signal: AbortSignal;
65
+ }
66
+ /** The bound runner face this layer consumes: S1-02's `BoundDecisionRunner`. */
67
+ export interface DiscoveryRunner {
68
+ identifyRoute(alias: string, scope: DiscoveryScope): DiscoveryRouteIdentity | undefined;
69
+ scope(originSeq?: number): DiscoveryScope;
70
+ run(request: DiscoveryDecisionRequest): Promise<DiscoveryDecisionRun>;
71
+ }
72
+ /**
73
+ * The host face the default resolver reads: the optional `systemoneDecisions`
74
+ * service mounted by S1-02's `decision-usage` plugin. Its absence is the
75
+ * design's "runner missing" row — a lexical fallback with no model call.
76
+ */
77
+ export interface DiscoveryHostFace {
78
+ readonly systemoneDecisions?: {
79
+ forAgent(actor: DiscoveryActor): DiscoveryRunner;
80
+ };
81
+ readonly ccSystemoneDecisions?: {
82
+ forAgent(actor: DiscoveryActor): DiscoveryRunner;
83
+ };
84
+ /** Optional guarded service getter (structurally cordis `ctx.get`). */
85
+ get?(name: string): unknown;
86
+ }
87
+ /**
88
+ * The default runner resolver: read the optional host service and bind it to
89
+ * the calling actor. Never throws — a service that refuses to bind is
90
+ * "unavailable", not a failed search.
91
+ *
92
+ * Resolution order (issue #359: tool-search is mounted at the bundle layer,
93
+ * the ROOT realm, where the isolate-scoped `systemoneDecisions` name has no
94
+ * implementation — the root-realm bridge `ccSystemoneDecisions`, published by
95
+ * `@dsh-cc/decision-usage` for exactly such out-of-group consumers, is the
96
+ * production landing):
97
+ *
98
+ * 1. `host.get('systemoneDecisions')` — the isolated name, so in-group hosts
99
+ * bind their OWN tree's instance (a second preset tree can overwrite the
100
+ * root bridge while each tree keeps its isolated service).
101
+ * 2. `host.get('ccSystemoneDecisions')` — the root-realm bridge.
102
+ * 3. Property fallbacks — the pre-bridge behavior, for structural hosts
103
+ * without a `get` seam.
104
+ *
105
+ * Each step is individually guarded: a throw (an isolate name crossing
106
+ * realms), an `undefined` result (no implementation in this realm's store) or
107
+ * a wrong-shaped value degrades to the NEXT step, never aborts resolution.
108
+ * @param host - the host context face (structurally the cordis context).
109
+ * @returns the resolver handed to `createDiscoveryRuntime`.
110
+ */
111
+ export declare function hostRunnerResolver(host: DiscoveryHostFace): (actor: DiscoveryActor) => DiscoveryRunner | undefined;
112
+ /**
113
+ * `catalogHash` — the approved resolution of the design's underspecified
114
+ * "catalog hash": `sha256` over the sorted `(name, description, searchHint)`
115
+ * triples of the eligible pool. A registration, an unload, or a description
116
+ * edit changes it, which invalidates every cached judgment (§ "Lifecycle,
117
+ * cache, and failure handling": "Candidate activation, registration, unload, or
118
+ * a limit change alters the key").
119
+ * @param candidates - the eligible pool.
120
+ * @returns an opaque `sha256:…` digest.
121
+ */
122
+ export declare function catalogHashOf(candidates: readonly DiscoveryCandidate[]): string;
123
+ /**
124
+ * `admissionHash` — the approved resolution of the design's underspecified
125
+ * "admission hash": `sha256` over the sorted `(name, isAdmitted)` pairs of the
126
+ * pool. The pool only holds admitted entries, so this pins the permission
127
+ * verdict the judgment was made under; a restriction applied during the
128
+ * judgment changes the pool and discards it at step 9.
129
+ * @param candidates - the eligible pool.
130
+ * @param entries - the snapshot the pool was built from (the verdict source).
131
+ * @returns an opaque `sha256:…` digest.
132
+ */
133
+ export declare function admissionHashOf(candidates: readonly DiscoveryCandidate[], entries: readonly DeferredEntry[]): string;
134
+ /**
135
+ * The judgment-shaping thresholds, camelCase, for the cache key (§ "Settings").
136
+ * The two cache knobs are deliberately absent: they govern reuse, not what a
137
+ * judgment means.
138
+ */
139
+ export declare function thresholdsOf(settings: DiscoverySettings): DiscoveryThresholds;
140
+ /** Whether two identities agree on ALL SEVEN fields (§ "File responsibilities"). */
141
+ export declare function sameIdentity(left: DiscoveryRouteIdentity, right: DiscoveryRouteIdentity): boolean;
142
+ /** Whether two metering scopes agree: a different scope is a different judgment. */
143
+ export declare function sameScope(left: DiscoveryScope, right: DiscoveryScope): boolean;
144
+ //# sourceMappingURL=discovery-contract.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"discovery-contract.d.ts","sourceRoot":"","sources":["../src/discovery-contract.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,144 @@
1
+ /**
2
+ * The structural boundary between tool discovery and S1-02's decision runtime:
3
+ * the request/response faces it consumes, the host resolver seam, and the two
4
+ * snapshot digests that pin a judgment to a catalog and an admission set.
5
+ *
6
+ * Design: `docs/plans/2026-11-02-systemone-05-tool-discovery.md`
7
+ * § "File responsibilities" (the runner comes from the optional
8
+ * `ctx.systemoneDecisions` service; re-read the identity after every await and
9
+ * compare all fields), § "Inputs, questions, and output", § "Lifecycle, cache,
10
+ * and failure handling" (what the cache key pins).
11
+ *
12
+ * These interfaces are declared STRUCTURALLY — exactly as `discovery.ts`
13
+ * declares the question and answer shapes — so `@dsh-cc/tool-search` never takes
14
+ * a dependency on the SystemOne client: the host passes its real
15
+ * `BoundDecisionRunner`/`DecisionRun` through these seams unchanged.
16
+ *
17
+ * @module @dsh-cc/tool-search/discovery-contract
18
+ */
19
+ import { createHash } from 'node:crypto';
20
+ /** The service shape both names must carry to be usable. */
21
+ function isRunnerService(value) {
22
+ return typeof value === 'object' && value !== null
23
+ && typeof value.forAgent === 'function';
24
+ }
25
+ /**
26
+ * The default runner resolver: read the optional host service and bind it to
27
+ * the calling actor. Never throws — a service that refuses to bind is
28
+ * "unavailable", not a failed search.
29
+ *
30
+ * Resolution order (issue #359: tool-search is mounted at the bundle layer,
31
+ * the ROOT realm, where the isolate-scoped `systemoneDecisions` name has no
32
+ * implementation — the root-realm bridge `ccSystemoneDecisions`, published by
33
+ * `@dsh-cc/decision-usage` for exactly such out-of-group consumers, is the
34
+ * production landing):
35
+ *
36
+ * 1. `host.get('systemoneDecisions')` — the isolated name, so in-group hosts
37
+ * bind their OWN tree's instance (a second preset tree can overwrite the
38
+ * root bridge while each tree keeps its isolated service).
39
+ * 2. `host.get('ccSystemoneDecisions')` — the root-realm bridge.
40
+ * 3. Property fallbacks — the pre-bridge behavior, for structural hosts
41
+ * without a `get` seam.
42
+ *
43
+ * Each step is individually guarded: a throw (an isolate name crossing
44
+ * realms), an `undefined` result (no implementation in this realm's store) or
45
+ * a wrong-shaped value degrades to the NEXT step, never aborts resolution.
46
+ * @param host - the host context face (structurally the cordis context).
47
+ * @returns the resolver handed to `createDiscoveryRuntime`.
48
+ */
49
+ export function hostRunnerResolver(host) {
50
+ const viaGet = (name) => {
51
+ try {
52
+ const service = host.get?.(name);
53
+ return isRunnerService(service) ? service : undefined;
54
+ }
55
+ catch {
56
+ return undefined;
57
+ }
58
+ };
59
+ return (actor) => {
60
+ const service = viaGet('systemoneDecisions')
61
+ ?? viaGet('ccSystemoneDecisions')
62
+ ?? (isRunnerService(host.systemoneDecisions) ? host.systemoneDecisions : undefined)
63
+ ?? (isRunnerService(host.ccSystemoneDecisions) ? host.ccSystemoneDecisions : undefined);
64
+ if (service === undefined)
65
+ return undefined;
66
+ try {
67
+ return service.forAgent(actor);
68
+ }
69
+ catch {
70
+ return undefined;
71
+ }
72
+ };
73
+ }
74
+ /** Total deterministic digest: `sha256:` over the JSON of the value. */
75
+ function digest(value) {
76
+ return `sha256:${createHash('sha256').update(JSON.stringify(value)).digest('hex')}`;
77
+ }
78
+ /** Name-ascending order, the id order {@link buildEligiblePool} assigns. */
79
+ function byName(left, right) {
80
+ return left.name.localeCompare(right.name);
81
+ }
82
+ /**
83
+ * `catalogHash` — the approved resolution of the design's underspecified
84
+ * "catalog hash": `sha256` over the sorted `(name, description, searchHint)`
85
+ * triples of the eligible pool. A registration, an unload, or a description
86
+ * edit changes it, which invalidates every cached judgment (§ "Lifecycle,
87
+ * cache, and failure handling": "Candidate activation, registration, unload, or
88
+ * a limit change alters the key").
89
+ * @param candidates - the eligible pool.
90
+ * @returns an opaque `sha256:…` digest.
91
+ */
92
+ export function catalogHashOf(candidates) {
93
+ return digest([...candidates].sort(byName).map(candidate => [candidate.name, candidate.description, candidate.searchHint ?? null]));
94
+ }
95
+ /**
96
+ * `admissionHash` — the approved resolution of the design's underspecified
97
+ * "admission hash": `sha256` over the sorted `(name, isAdmitted)` pairs of the
98
+ * pool. The pool only holds admitted entries, so this pins the permission
99
+ * verdict the judgment was made under; a restriction applied during the
100
+ * judgment changes the pool and discards it at step 9.
101
+ * @param candidates - the eligible pool.
102
+ * @param entries - the snapshot the pool was built from (the verdict source).
103
+ * @returns an opaque `sha256:…` digest.
104
+ */
105
+ export function admissionHashOf(candidates, entries) {
106
+ const admitted = new Map(entries.map(entry => [entry.name, entry.admitted]));
107
+ return digest([...candidates].sort(byName).map(candidate => [candidate.name, admitted.get(candidate.name) === true]));
108
+ }
109
+ /**
110
+ * The judgment-shaping thresholds, camelCase, for the cache key (§ "Settings").
111
+ * The two cache knobs are deliberately absent: they govern reuse, not what a
112
+ * judgment means.
113
+ */
114
+ export function thresholdsOf(settings) {
115
+ return {
116
+ timeoutMs: settings.timeoutMs,
117
+ maxInputTokens: settings.maxInputTokens,
118
+ maxCandidates: settings.maxCandidates,
119
+ batchSize: settings.batchSize,
120
+ maxQueryChars: settings.maxQueryChars,
121
+ maxMetadataChars: settings.maxMetadataChars,
122
+ minRelevanceIndex: settings.minRelevanceIndex,
123
+ minDirectFit: settings.minDirectFit,
124
+ maxActivations: settings.maxActivations,
125
+ };
126
+ }
127
+ /** Whether two identities agree on ALL SEVEN fields (§ "File responsibilities"). */
128
+ export function sameIdentity(left, right) {
129
+ return left.provider === right.provider
130
+ && left.model === right.model
131
+ && left.revision === right.revision
132
+ && left.perRequestTokens === right.perRequestTokens
133
+ && left.perQuestionTokens === right.perQuestionTokens
134
+ && left.maxQuestions === right.maxQuestions
135
+ && left.maxOutputTokens === right.maxOutputTokens;
136
+ }
137
+ /** Whether two metering scopes agree: a different scope is a different judgment. */
138
+ export function sameScope(left, right) {
139
+ return left.projectKey === right.projectKey
140
+ && left.sessionId === right.sessionId
141
+ && left.agentId === right.agentId
142
+ && left.originSeq === right.originSeq;
143
+ }
144
+ //# sourceMappingURL=discovery-contract.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"discovery-contract.js","sourceRoot":"","sources":["../src/discovery-contract.ts"],"names":[],"mappings":"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"}