@agentspec/sdk 0.4.0 → 0.5.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 +46 -0
- package/dist/evidence-points-C6j4PSsQ.d.cts +1139 -0
- package/dist/evidence-points-C6j4PSsQ.d.ts +1139 -0
- package/dist/index.cjs +1727 -345
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +1026 -2549
- package/dist/index.d.ts +1026 -2549
- package/dist/index.js +1678 -344
- package/dist/index.js.map +1 -1
- package/dist/runtime.cjs +930 -0
- package/dist/runtime.cjs.map +1 -0
- package/dist/runtime.d.cts +63 -0
- package/dist/runtime.d.ts +63 -0
- package/dist/runtime.js +921 -0
- package/dist/runtime.js.map +1 -0
- package/package.json +15 -8
- package/schemas/evidence/v1/contract.schema.json +2078 -0
- package/schemas/evidence/v1/fixtures/drifted/EvalResult.n-as-string.json +1 -0
- package/schemas/evidence/v1/fixtures/drifted/EvalResult.pass-rate-above-one.json +1 -0
- package/schemas/evidence/v1/fixtures/drifted/EvidenceRecord.bad-sha.json +1 -0
- package/schemas/evidence/v1/fixtures/drifted/EvidenceRecord.extra-field.json +1 -0
- package/schemas/evidence/v1/fixtures/drifted/EvidenceRecord.fail-without-reason.json +1 -0
- package/schemas/evidence/v1/fixtures/drifted/EvidenceRecord.missing-ttl.json +1 -0
- package/schemas/evidence/v1/fixtures/drifted/EvidenceRecord.not-verifiable-without-reason.json +1 -0
- package/schemas/evidence/v1/fixtures/drifted/EvidenceRecord.observed-at-epoch.json +1 -0
- package/schemas/evidence/v1/fixtures/drifted/EvidenceRecord.observed-at-out-of-range.json +1 -0
- package/schemas/evidence/v1/fixtures/drifted/EvidenceRecord.observed-at-space-separated.json +1 -0
- package/schemas/evidence/v1/fixtures/drifted/EvidenceRecord.sample-size-boolean.json +1 -0
- package/schemas/evidence/v1/fixtures/drifted/EvidenceRecord.ttl-as-string.json +1 -0
- package/schemas/evidence/v1/fixtures/drifted/EvidenceRecord.unknown-collector.json +1 -0
- package/schemas/evidence/v1/fixtures/drifted/EvidenceRecord.unknown-source.json +1 -0
- package/schemas/evidence/v1/fixtures/drifted/Heartbeat.bad-contract-version.json +1 -0
- package/schemas/evidence/v1/fixtures/drifted/Heartbeat.bad-record.json +1 -0
- package/schemas/evidence/v1/fixtures/drifted/Heartbeat.point-records-over-limit.json +1 -0
- package/schemas/evidence/v1/fixtures/drifted/Heartbeat.with-gap.json +1 -0
- package/schemas/evidence/v1/fixtures/drifted/ReadinessFinding.bad-severity.json +1 -0
- package/schemas/evidence/v1/fixtures/drifted/SidecarPush.missing-sha.json +1 -0
- package/schemas/evidence/v1/fixtures/drifted/TrustPolicy.lenient.json +1 -0
- package/schemas/evidence/v1/fixtures/valid/EvalResult.live.json +1 -0
- package/schemas/evidence/v1/fixtures/valid/EvalResult.null-dataset.json +1 -0
- package/schemas/evidence/v1/fixtures/valid/EvidenceRecord.fail.json +1 -0
- package/schemas/evidence/v1/fixtures/valid/EvidenceRecord.null-collector.json +1 -0
- package/schemas/evidence/v1/fixtures/valid/EvidenceRecord.pass-null-reason.json +1 -0
- package/schemas/evidence/v1/fixtures/valid/EvidenceRecord.pass.json +1 -0
- package/schemas/evidence/v1/fixtures/valid/EvidenceRecord.timezone-offset.json +1 -0
- package/schemas/evidence/v1/fixtures/valid/EvidenceRecord.unknown-reason-code.json +1 -0
- package/schemas/evidence/v1/fixtures/valid/EvidenceRecord.with-collector.json +1 -0
- package/schemas/evidence/v1/fixtures/valid/Heartbeat.contract-null.json +1 -0
- package/schemas/evidence/v1/fixtures/valid/Heartbeat.contract-version.json +1 -0
- package/schemas/evidence/v1/fixtures/valid/Heartbeat.evidence-points.json +1 -0
- package/schemas/evidence/v1/fixtures/valid/Heartbeat.full.json +1 -0
- package/schemas/evidence/v1/fixtures/valid/Heartbeat.sdk-no-records.json +1 -0
- package/schemas/evidence/v1/fixtures/valid/Heartbeat.sdk.json +1 -0
- package/schemas/evidence/v1/fixtures/valid/ReadinessFinding.open-code.json +1 -0
- package/schemas/evidence/v1/fixtures/valid/ReadinessFinding.with-subject.json +1 -0
- package/schemas/evidence/v1/fixtures/valid/SidecarPush.declared.json +1 -0
- package/schemas/evidence/v1/fixtures/valid/TrustPolicy.standard.json +1 -0
- package/schemas/evidence/v1/fixtures/valid/TrustPolicy.strict.json +1 -0
- package/schemas/grader/v1/fixtures/accepts-fractional-seconds.json +62 -0
- package/schemas/grader/v1/fixtures/accepts-leap-day-in-year-below-100.json +62 -0
- package/schemas/grader/v1/fixtures/accepts-more-than-6-fractional-digits.json +62 -0
- package/schemas/grader/v1/fixtures/accepts-numeric-offset.json +62 -0
- package/schemas/grader/v1/fixtures/all-records-must-pass.json +58 -0
- package/schemas/grader/v1/fixtures/below-threshold-not-graded.json +61 -0
- package/schemas/grader/v1/fixtures/derived-rule-fails-when-a-parent-fails.json +67 -0
- package/schemas/grader/v1/fixtures/derived-rule-follows-memory-write-parent.json +43 -0
- package/schemas/grader/v1/fixtures/derived-rule-passes-with-its-parents.json +64 -0
- package/schemas/grader/v1/fixtures/derived-rule-unverified-when-a-parent-has-no-evidence.json +51 -0
- package/schemas/grader/v1/fixtures/expired-record-is-stale.json +66 -0
- package/schemas/grader/v1/fixtures/fail-beats-not-verifiable.json +62 -0
- package/schemas/grader/v1/fixtures/grade-band-b.json +62 -0
- package/schemas/grader/v1/fixtures/independent-from-listed-collector-is-admitted.json +39 -0
- package/schemas/grader/v1/fixtures/independent-from-unlisted-collector-is-rejected.json +47 -0
- package/schemas/grader/v1/fixtures/low-severity-coverage-only.json +90 -0
- package/schemas/grader/v1/fixtures/malformed-point-is-ignored.json +67 -0
- package/schemas/grader/v1/fixtures/never-admitted-sources-standard.json +196 -0
- package/schemas/grader/v1/fixtures/never-admitted-sources-strict.json +196 -0
- package/schemas/grader/v1/fixtures/not-admitted-outranks-mismatch.json +64 -0
- package/schemas/grader/v1/fixtures/not-verifiable-ignored-when-one-passes.json +58 -0
- package/schemas/grader/v1/fixtures/not-verifiable-only-keeps-reason.json +71 -0
- package/schemas/grader/v1/fixtures/not-wired-point-drops-a-fail-when-no-point-of-the-rule-is-wired.json +59 -0
- package/schemas/grader/v1/fixtures/not-wired-point-drops-a-wired-point-pass.json +87 -0
- package/schemas/grader/v1/fixtures/not-wired-point-drops-its-own-earlier-fail-when-another-point-is-wired.json +70 -0
- package/schemas/grader/v1/fixtures/not-wired-point-ignores-a-wired-point-fail-without-the-rule-id.json +69 -0
- package/schemas/grader/v1/fixtures/not-wired-point-keeps-a-wired-point-fail.json +79 -0
- package/schemas/grader/v1/fixtures/not-wired-point-keeps-independent-evidence.json +64 -0
- package/schemas/grader/v1/fixtures/not-wired-point-never-passes.json +107 -0
- package/schemas/grader/v1/fixtures/offline-record-is-not-admitted-yet.json +47 -0
- package/schemas/grader/v1/fixtures/record-without-collector-is-admitted-until-producers-set-it.json +38 -0
- package/schemas/grader/v1/fixtures/records-without-rule-id-never-graded.json +62 -0
- package/schemas/grader/v1/fixtures/rejects-compact-timestamp.json +56 -0
- package/schemas/grader/v1/fixtures/rejects-hour-24-lowercase-separator.json +56 -0
- package/schemas/grader/v1/fixtures/rejects-hour-24-space-separator.json +56 -0
- package/schemas/grader/v1/fixtures/rejects-hour-24.json +56 -0
- package/schemas/grader/v1/fixtures/rejects-impossible-date-feb-29.json +56 -0
- package/schemas/grader/v1/fixtures/rejects-lowercase-t.json +56 -0
- package/schemas/grader/v1/fixtures/rejects-lowercase-z.json +56 -0
- package/schemas/grader/v1/fixtures/rejects-offset-hours-above-23.json +56 -0
- package/schemas/grader/v1/fixtures/rejects-offset-minutes-above-59.json +56 -0
- package/schemas/grader/v1/fixtures/rejects-offsetless-timestamp.json +56 -0
- package/schemas/grader/v1/fixtures/rejects-space-separator.json +56 -0
- package/schemas/grader/v1/fixtures/rejects-year-zero.json +56 -0
- package/schemas/grader/v1/fixtures/rounds-coverage-before-the-threshold.json +850 -0
- package/schemas/grader/v1/fixtures/rounds-verified-before-the-band.json +674 -0
- package/schemas/grader/v1/fixtures/sdk-observed-from-evidence-point-rule-is-admitted-standard.json +39 -0
- package/schemas/grader/v1/fixtures/sdk-observed-from-evidence-point-rule-is-not-admitted-strict.json +47 -0
- package/schemas/grader/v1/fixtures/sdk-observed-standard.json +58 -0
- package/schemas/grader/v1/fixtures/sdk-observed-strict.json +66 -0
- package/schemas/grader/v1/fixtures/sdk-observed-without-evidence-point-source-is-rejected.json +47 -0
- package/schemas/grader/v1/fixtures/sdk-only-agent-all-points-fired.json +116 -0
- package/schemas/grader/v1/fixtures/stale-outranks-mismatch.json +64 -0
- package/schemas/grader/v1/fixtures/strict-admits-independent.json +39 -0
- package/schemas/grader/v1/fixtures/sub-millisecond-expiry-boundary.json +38 -0
- package/schemas/v1/agent.schema.json +372 -198
package/dist/runtime.js
ADDED
|
@@ -0,0 +1,921 @@
|
|
|
1
|
+
import { createHash } from 'crypto';
|
|
2
|
+
import 'js-yaml';
|
|
3
|
+
import { z } from 'zod';
|
|
4
|
+
import { AsyncLocalStorage } from 'async_hooks';
|
|
5
|
+
|
|
6
|
+
// src/manifest-hash.ts
|
|
7
|
+
function canonicalJson(value) {
|
|
8
|
+
if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
|
|
9
|
+
if (value !== null && typeof value === "object") {
|
|
10
|
+
const obj = value;
|
|
11
|
+
const members = Object.keys(obj).filter((k) => obj[k] !== void 0).sort();
|
|
12
|
+
return `{${members.map((k) => `${JSON.stringify(k)}:${canonicalJson(obj[k])}`).join(",")}}`;
|
|
13
|
+
}
|
|
14
|
+
return JSON.stringify(value);
|
|
15
|
+
}
|
|
16
|
+
function canonicalManifestSha256(manifest) {
|
|
17
|
+
return createHash("sha256").update(canonicalJson(manifest), "utf8").digest("hex");
|
|
18
|
+
}
|
|
19
|
+
var EvidenceClass = z.enum(["independent", "evidence-point", "offline", "declared"]);
|
|
20
|
+
var Collector = z.enum([
|
|
21
|
+
"gateway-config",
|
|
22
|
+
"gateway-traffic",
|
|
23
|
+
"sidecar-probe",
|
|
24
|
+
"sidecar-forwarder",
|
|
25
|
+
"sidecar-eval",
|
|
26
|
+
"operator-webhook",
|
|
27
|
+
"operator-logs",
|
|
28
|
+
"sdk",
|
|
29
|
+
"lock",
|
|
30
|
+
"manifest"
|
|
31
|
+
]);
|
|
32
|
+
var EvidencePoint = z.enum(["guardrail", "tool", "mcpClient", "memoryWrite", "vectorStore", "logging"]);
|
|
33
|
+
var Scope = z.enum(["declared", "configured", "enforced", "observed", "ran-where-wired", "every-path", "effective"]);
|
|
34
|
+
var WiredBy = z.enum(["none", "operator-render", "agent-code", "user-schedule", "opt-in"]);
|
|
35
|
+
var Mode = z.enum(["standalone", "operator"]);
|
|
36
|
+
var BuildStatus = z.enum(["built", "partial", "planned", "open"]);
|
|
37
|
+
var RuleEvidenceSource = z.object({
|
|
38
|
+
class: EvidenceClass,
|
|
39
|
+
collector: Collector,
|
|
40
|
+
/** Evidence-point sources only. */
|
|
41
|
+
point: EvidencePoint.nullish(),
|
|
42
|
+
proves: Scope,
|
|
43
|
+
wiredBy: WiredBy,
|
|
44
|
+
modes: z.array(Mode).min(1),
|
|
45
|
+
status: BuildStatus,
|
|
46
|
+
/** A variant such as HTTP MCP, stdio MCP, local tools or opt-in. */
|
|
47
|
+
when: z.string().min(1).nullish(),
|
|
48
|
+
/** A collector that checks the counts, such as gateway calls against guardrail records. */
|
|
49
|
+
crossCheck: Collector.nullish(),
|
|
50
|
+
/** The `agentspec lock` prompt question. */
|
|
51
|
+
question: z.string().min(1).nullish()
|
|
52
|
+
}).strict().refine((s) => s.class === "evidence-point" === (s.point != null), {
|
|
53
|
+
message: "an evidence-point source names its `point`, and no other class does"
|
|
54
|
+
});
|
|
55
|
+
var RuleEvidenceEntry = z.object({
|
|
56
|
+
sources: z.array(RuleEvidenceSource).default([]),
|
|
57
|
+
/** Rules whose verdicts decide this one (all must pass); this rule inherits their sources. */
|
|
58
|
+
derivedFrom: z.array(z.string().min(1)).nullish(),
|
|
59
|
+
/** What a pass does not prove, shown with the result. Free text. */
|
|
60
|
+
notProven: z.string().nullish()
|
|
61
|
+
}).strict().refine((e) => e.sources.length > 0 || (e.derivedFrom?.length ?? 0) > 0, {
|
|
62
|
+
message: "an entry needs at least one source or a `derivedFrom`"
|
|
63
|
+
});
|
|
64
|
+
var BOTH = ["standalone", "operator"];
|
|
65
|
+
var CLASS_DEFAULTS = {
|
|
66
|
+
independent: { wiredBy: "none", status: "built" },
|
|
67
|
+
"evidence-point": { wiredBy: "agent-code", status: "planned" },
|
|
68
|
+
offline: { wiredBy: "user-schedule", status: "planned" },
|
|
69
|
+
declared: { wiredBy: "none", status: "built" }
|
|
70
|
+
};
|
|
71
|
+
var source = (cls, collector, proves, extra = {}) => ({ class: cls, collector, proves, modes: BOTH, ...CLASS_DEFAULTS[cls], ...extra });
|
|
72
|
+
var independent = (collector, proves, extra) => source("independent", collector, proves, extra);
|
|
73
|
+
var point = (p, proves, extra) => source("evidence-point", "sdk", proves, { point: p, ...extra });
|
|
74
|
+
var lock = (question, extra) => source("offline", "lock", "every-path", { question, ...extra });
|
|
75
|
+
var declared = (extra) => source("declared", "manifest", "declared", extra);
|
|
76
|
+
var OPERATOR_ONLY = { modes: ["operator"] };
|
|
77
|
+
var PLANNED = { status: "planned" };
|
|
78
|
+
var WRITES_BYPASS = "Writes that bypass the evidence point at runtime.";
|
|
79
|
+
var entries = {
|
|
80
|
+
"MODEL-01": { sources: [independent("gateway-config", "configured"), independent("gateway-traffic", "observed")] },
|
|
81
|
+
"MODEL-02": {
|
|
82
|
+
sources: [independent("gateway-traffic", "observed"), independent("gateway-config", "configured", PLANNED)]
|
|
83
|
+
},
|
|
84
|
+
"MODEL-03": { sources: [independent("gateway-config", "enforced")] },
|
|
85
|
+
"MODEL-04": {
|
|
86
|
+
sources: [
|
|
87
|
+
independent("gateway-config", "enforced"),
|
|
88
|
+
lock("Do the agent's own provider clients retry more than spec.model.fallback.maxRetries, or stack retries on the gateway's?", { when: "client retries" })
|
|
89
|
+
],
|
|
90
|
+
notProven: "That the gateway's attempts match `spec.model.fallback.maxRetries` at runtime beyond the rendered config."
|
|
91
|
+
},
|
|
92
|
+
"MODEL-05": {
|
|
93
|
+
sources: [independent("gateway-traffic", "observed", { when: "agw.ai.usage.cost.total" })],
|
|
94
|
+
notProven: "Requests with no token usage: not counted."
|
|
95
|
+
},
|
|
96
|
+
"SEC-LLM-01": {
|
|
97
|
+
sources: [
|
|
98
|
+
independent("sidecar-probe", "effective", { when: "opt-in", wiredBy: "opt-in", status: "planned" }),
|
|
99
|
+
point("guardrail", "ran-where-wired"),
|
|
100
|
+
lock("Does every path that sends user input to a model run the declared input guardrails first?")
|
|
101
|
+
]
|
|
102
|
+
},
|
|
103
|
+
"SEC-LLM-02": {
|
|
104
|
+
sources: [
|
|
105
|
+
point("guardrail", "ran-where-wired"),
|
|
106
|
+
lock("Does every path that returns model output run the declared output guardrails first?")
|
|
107
|
+
],
|
|
108
|
+
notProven: "Effective: a no-op output guardrail still fires."
|
|
109
|
+
},
|
|
110
|
+
"SEC-LLM-03": { sources: [declared()] },
|
|
111
|
+
"SEC-LLM-04": {
|
|
112
|
+
sources: [independent("gateway-config", "enforced"), independent("gateway-traffic", "observed", PLANNED)],
|
|
113
|
+
notProven: "Cost: MODEL-03 covers it."
|
|
114
|
+
},
|
|
115
|
+
"SEC-LLM-05": {
|
|
116
|
+
sources: [independent("gateway-traffic", "observed"), independent("gateway-config", "configured", PLANNED)]
|
|
117
|
+
},
|
|
118
|
+
"SEC-LLM-06": { derivedFrom: ["MEM-01"], notProven: "Same as MEM-01." },
|
|
119
|
+
"SEC-LLM-07": {
|
|
120
|
+
sources: [
|
|
121
|
+
independent("sidecar-probe", "configured", { when: "HTTP MCP" }),
|
|
122
|
+
point("mcpClient", "ran-where-wired", { when: "stdio MCP" }),
|
|
123
|
+
lock("Does the agent call any MCP tool the manifest does not declare, or one that serves no annotations?"),
|
|
124
|
+
declared({ when: "local tools" })
|
|
125
|
+
]
|
|
126
|
+
},
|
|
127
|
+
"SEC-LLM-08": {
|
|
128
|
+
sources: [
|
|
129
|
+
independent("sidecar-probe", "configured", PLANNED),
|
|
130
|
+
independent("gateway-traffic", "enforced", PLANNED),
|
|
131
|
+
point("mcpClient", "ran-where-wired", { when: "stdio MCP" })
|
|
132
|
+
],
|
|
133
|
+
notProven: "Which tools are destructive: the server declares it; nothing checks the claim."
|
|
134
|
+
},
|
|
135
|
+
"SEC-LLM-09": { derivedFrom: ["EVAL-01", "EVAL-02"] },
|
|
136
|
+
"SEC-LLM-10": {
|
|
137
|
+
sources: [
|
|
138
|
+
independent("operator-webhook", "configured", { ...OPERATOR_ONLY, ...PLANNED }),
|
|
139
|
+
declared({ modes: ["standalone"] })
|
|
140
|
+
]
|
|
141
|
+
},
|
|
142
|
+
"TOOL-01": {
|
|
143
|
+
sources: [
|
|
144
|
+
independent("gateway-traffic", "observed", { when: "HTTP MCP" }),
|
|
145
|
+
point("tool", "ran-where-wired", { when: "local tools" }),
|
|
146
|
+
point("mcpClient", "ran-where-wired", { when: "stdio MCP" }),
|
|
147
|
+
lock("Which tools does the agent code register or call, local, HTTP MCP and stdio MCP?")
|
|
148
|
+
],
|
|
149
|
+
notProven: "Unwrapped local or stdio calls at runtime: only the lock inventory catches them."
|
|
150
|
+
},
|
|
151
|
+
"MEM-01": {
|
|
152
|
+
sources: [
|
|
153
|
+
point("memoryWrite", "enforced"),
|
|
154
|
+
lock("Does every memory write pass through the PII scrubber for the declared fields?")
|
|
155
|
+
],
|
|
156
|
+
notProven: "Full coverage: the scrubber is a regex baseline (Presidio optional in Python). " + WRITES_BYPASS
|
|
157
|
+
},
|
|
158
|
+
"MEM-02": {
|
|
159
|
+
sources: [
|
|
160
|
+
point("memoryWrite", "enforced"),
|
|
161
|
+
lock("Does every memory write apply the declared retention TTL?")
|
|
162
|
+
],
|
|
163
|
+
notProven: WRITES_BYPASS + " Backends that cannot apply a TTL (record `ttl: unsupported`): the evidence point is `not_verifiable` there and only the lock remains."
|
|
164
|
+
},
|
|
165
|
+
"MEM-03": {
|
|
166
|
+
sources: [
|
|
167
|
+
point("memoryWrite", "enforced"),
|
|
168
|
+
lock("Does every memory write honour the declared memory audit setting?")
|
|
169
|
+
],
|
|
170
|
+
notProven: WRITES_BYPASS
|
|
171
|
+
},
|
|
172
|
+
"MEM-04": {
|
|
173
|
+
sources: [
|
|
174
|
+
point("vectorStore", "ran-where-wired"),
|
|
175
|
+
lock("Does every vector store query and write use the declared namespace or tenant isolation?")
|
|
176
|
+
],
|
|
177
|
+
notProven: "Isolation: the right namespace does not prove other tenants cannot read it."
|
|
178
|
+
},
|
|
179
|
+
"MEM-05": {
|
|
180
|
+
sources: [independent("gateway-traffic", "observed", { when: "gen_ai.usage.output_tokens" }), declared({ when: "until a call is observed" })],
|
|
181
|
+
notProven: "The tolerance for the system prompt and tool schemas is set in Phase 2, with an ADR-0015 amendment; a call without gen_ai.usage.output_tokens leaves the check not_verifiable."
|
|
182
|
+
},
|
|
183
|
+
"EVAL-01": { sources: [independent("sidecar-eval", "observed", PLANNED)] },
|
|
184
|
+
"EVAL-02": {
|
|
185
|
+
sources: [
|
|
186
|
+
independent("sidecar-eval", "observed", PLANNED),
|
|
187
|
+
lock("Does the agent's CI run the declared evaluation gate before deploy?")
|
|
188
|
+
],
|
|
189
|
+
notProven: "That a failed gate actually blocks a deploy: CI is outside the system."
|
|
190
|
+
},
|
|
191
|
+
"EVAL-03": { sources: [independent("sidecar-eval", "observed", PLANNED)] },
|
|
192
|
+
"OBS-01": {
|
|
193
|
+
sources: [independent("sidecar-forwarder", "observed"), independent("sidecar-probe", "configured")],
|
|
194
|
+
notProven: "That the agent exports every span: the rule is about the backend, not span coverage. agentops is not a target: it has no OTLP ingest."
|
|
195
|
+
},
|
|
196
|
+
"OBS-02": {
|
|
197
|
+
sources: [
|
|
198
|
+
independent("operator-logs", "observed", { ...OPERATOR_ONLY, ...PLANNED }),
|
|
199
|
+
point("logging", "ran-where-wired"),
|
|
200
|
+
lock("Does every log statement emit structured JSON?")
|
|
201
|
+
]
|
|
202
|
+
},
|
|
203
|
+
"OBS-03": {
|
|
204
|
+
sources: [
|
|
205
|
+
independent("operator-logs", "observed", { ...OPERATOR_ONLY, ...PLANNED }),
|
|
206
|
+
lock("Does any log statement write one of the declared sensitive fields?")
|
|
207
|
+
],
|
|
208
|
+
notProven: "Full coverage: the scanner is a regex and pattern baseline, so recall is limited."
|
|
209
|
+
},
|
|
210
|
+
"META-01": { sources: [declared()] },
|
|
211
|
+
"META-02": {
|
|
212
|
+
sources: [independent("gateway-traffic", "observed", { when: "gen_ai.request.temperature" })],
|
|
213
|
+
notProven: "Requests that set no temperature: `not_verifiable`, not counted."
|
|
214
|
+
}
|
|
215
|
+
};
|
|
216
|
+
var RULE_EVIDENCE = Object.fromEntries(
|
|
217
|
+
Object.entries(entries).map(([id, entry]) => [id, RuleEvidenceEntry.parse(entry)])
|
|
218
|
+
);
|
|
219
|
+
var EvidenceStatus = z.enum(["pass", "fail", "not_verifiable"]);
|
|
220
|
+
var EvidenceSource = z.enum(["independent", "sdk-observed", "lower-bound", "self-declared", "declared", "offline"]);
|
|
221
|
+
var EvidenceOrigin = z.enum(["ingress", "gateway", "egress_proxy", "in_process", "probe", "manifest", "judge"]);
|
|
222
|
+
var SeveritySchema = z.enum(["critical", "high", "medium", "low", "info"]);
|
|
223
|
+
z.enum(["standard", "strict"]);
|
|
224
|
+
var EvidenceReason = z.object({ code: z.string().min(1), detail: z.string().nullish() }).strict();
|
|
225
|
+
var TIMESTAMP_PATTERN = /^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])T([01]\d|2[0-3]):[0-5]\d:[0-5]\d(\.\d+)?(Z|[+-]\d{2}:\d{2})$/;
|
|
226
|
+
var Timestamp = z.string().regex(TIMESTAMP_PATTERN);
|
|
227
|
+
var EvidenceWindow = z.object({ start: Timestamp, end: Timestamp }).strict();
|
|
228
|
+
var Sha256 = z.string().regex(/^[a-f0-9]{64}$/);
|
|
229
|
+
var MAX_TRACE_IDS = 20;
|
|
230
|
+
var recordFields = {
|
|
231
|
+
/** Scoped per subject: `tool:<name>`, `model:<id>`, or a bare check name for agent-wide checks. */
|
|
232
|
+
checkId: z.string().min(1),
|
|
233
|
+
ruleId: z.string().min(1).nullish(),
|
|
234
|
+
source: EvidenceSource,
|
|
235
|
+
origin: EvidenceOrigin,
|
|
236
|
+
/** The registry collector that produced the record. Optional until every producer sets it (#422); checking it against the collectors the registry lists for the rule is the grader's job (#423). */
|
|
237
|
+
collector: Collector.nullish(),
|
|
238
|
+
observedAt: Timestamp,
|
|
239
|
+
window: EvidenceWindow,
|
|
240
|
+
ttlSeconds: z.number().int().nonnegative(),
|
|
241
|
+
sampleSize: z.number().int().nonnegative(),
|
|
242
|
+
traceIds: z.array(z.string().min(1)).max(MAX_TRACE_IDS),
|
|
243
|
+
manifestSha256: Sha256
|
|
244
|
+
};
|
|
245
|
+
var EvidenceRecordPass = z.object({ ...recordFields, status: z.literal("pass"), reason: EvidenceReason.nullish() }).strict();
|
|
246
|
+
var EvidenceRecordNotPass = z.object({
|
|
247
|
+
...recordFields,
|
|
248
|
+
status: z.enum(["fail", "not_verifiable"]),
|
|
249
|
+
reason: EvidenceReason
|
|
250
|
+
}).strict();
|
|
251
|
+
var EvidenceRecord = z.union([EvidenceRecordPass, EvidenceRecordNotPass]);
|
|
252
|
+
z.object({ code: z.string().min(1), subject: z.string().min(1), message: z.string().min(1) }).strict();
|
|
253
|
+
z.object({
|
|
254
|
+
code: z.string().min(1),
|
|
255
|
+
severity: SeveritySchema,
|
|
256
|
+
message: z.string().min(1),
|
|
257
|
+
subject: z.string().nullish(),
|
|
258
|
+
ruleIds: z.array(z.string().min(1)).nullish()
|
|
259
|
+
}).strict();
|
|
260
|
+
z.object({
|
|
261
|
+
metric: z.string().min(1),
|
|
262
|
+
n: z.number().int().nonnegative(),
|
|
263
|
+
passRate: z.number().min(0).max(1),
|
|
264
|
+
ciLow: z.number().min(0).max(1),
|
|
265
|
+
ciHigh: z.number().min(0).max(1),
|
|
266
|
+
threshold: z.number().min(0).max(1),
|
|
267
|
+
window: EvidenceWindow,
|
|
268
|
+
judgeModel: z.string().min(1),
|
|
269
|
+
rubricHash: Sha256,
|
|
270
|
+
source: EvidenceSource,
|
|
271
|
+
dataset: z.string().min(1).nullish()
|
|
272
|
+
}).strict();
|
|
273
|
+
var MAX_POINT_RECORDS = 5;
|
|
274
|
+
var EvidencePointState = z.enum(["fired", "wired", "not_wired"]);
|
|
275
|
+
var EvidencePointAggregate = z.object({
|
|
276
|
+
point: EvidencePoint,
|
|
277
|
+
/** What the point is wired on, a key of `CONTRACT.evidencePoints[point]`. */
|
|
278
|
+
target: z.string().min(1),
|
|
279
|
+
state: EvidencePointState,
|
|
280
|
+
counts: z.object({
|
|
281
|
+
pass: z.number().int().nonnegative(),
|
|
282
|
+
fail: z.number().int().nonnegative(),
|
|
283
|
+
not_verifiable: z.number().int().nonnegative()
|
|
284
|
+
}).strict(),
|
|
285
|
+
records: z.array(EvidenceRecord).max(MAX_POINT_RECORDS)
|
|
286
|
+
}).strict();
|
|
287
|
+
var Passthrough = z.record(z.string(), z.unknown());
|
|
288
|
+
z.object({
|
|
289
|
+
/** Contract version of the sending SDK (`CONTRACT.version`); absent or null from older SDKs. */
|
|
290
|
+
contract: z.string().regex(/^\d+\.\d+\.\d+$/).nullish(),
|
|
291
|
+
health: Passthrough,
|
|
292
|
+
records: z.array(EvidenceRecord).default([]),
|
|
293
|
+
/** Every evidence point the registry gives for the manifest, wired or not; absent from older SDKs. */
|
|
294
|
+
evidencePoints: z.array(EvidencePointAggregate).default([]),
|
|
295
|
+
usage: Passthrough.nullish(),
|
|
296
|
+
tools: Passthrough.nullish()
|
|
297
|
+
}).strict();
|
|
298
|
+
z.object({
|
|
299
|
+
manifestSha256: Sha256,
|
|
300
|
+
declared: Passthrough.nullish(),
|
|
301
|
+
records: z.array(EvidenceRecord).default([])
|
|
302
|
+
}).strict();
|
|
303
|
+
|
|
304
|
+
// src/schema/contract.schema.ts
|
|
305
|
+
var fixed = (value) => z.literal(value).default(value);
|
|
306
|
+
var REASON_CODES = [
|
|
307
|
+
"stale",
|
|
308
|
+
"source_not_admitted",
|
|
309
|
+
"source_mismatch",
|
|
310
|
+
"no_evidence",
|
|
311
|
+
"not_wired",
|
|
312
|
+
"no_calls_observed",
|
|
313
|
+
"no_failover_observed",
|
|
314
|
+
"no_budget_evidence",
|
|
315
|
+
"no_approval_token_evidence",
|
|
316
|
+
"no_retrieval_spans",
|
|
317
|
+
"unrecognised_conventions",
|
|
318
|
+
"instrumentation_unavailable",
|
|
319
|
+
"declared_env_missing",
|
|
320
|
+
"provider_key_on_agent",
|
|
321
|
+
"response_cap_exceeded",
|
|
322
|
+
"temperature_above_max",
|
|
323
|
+
"undeclared_tool",
|
|
324
|
+
"undeclared_model",
|
|
325
|
+
"unpinned_model",
|
|
326
|
+
"self_declared",
|
|
327
|
+
"unpriced_model",
|
|
328
|
+
"undeclared_namespace"
|
|
329
|
+
];
|
|
330
|
+
var ContractSchema = z.object({
|
|
331
|
+
/** Contract version (major.minor.patch) a heartbeat carries: a receiver rejects another major and accepts a newer minor (ADR-0039). */
|
|
332
|
+
version: fixed("1.0.0"),
|
|
333
|
+
env: z.object({
|
|
334
|
+
manifestPath: fixed("MANIFEST_PATH"),
|
|
335
|
+
upstreamUrl: fixed("UPSTREAM_URL"),
|
|
336
|
+
proxyPort: fixed("PROXY_PORT"),
|
|
337
|
+
controlPlanePort: fixed("CONTROL_PLANE_PORT"),
|
|
338
|
+
/** Control plane URL the operator webhook injects into the sidecar and agent containers; SDK push mode falls back to it. */
|
|
339
|
+
controlPlaneUrl: fixed("AGENTSPEC_CONTROL_PLANE_URL"),
|
|
340
|
+
/** Agent JWT from `POST /api/v1/register`; `agentspec register` sends it to the control plane as a Bearer token. The sidecar's own push needs the `sidecarToken` from the same call (see `agentTokenSecretSuffix`). */
|
|
341
|
+
agentKey: fixed("AGENTSPEC_API_KEY"),
|
|
342
|
+
/** Trust policy (`standard | strict`) the grader applies: set on the control plane and the sidecar, never in `agent.yaml` (ADR-0007). */
|
|
343
|
+
trustPolicy: fixed("AGENTSPEC_TRUST_POLICY"),
|
|
344
|
+
/** The webhook's PodSpec findings (the `agentspec.io/podspec-findings` annotation, JSON), injected into the sidecar by the downward API (ADR-0019). */
|
|
345
|
+
podspecFindings: fixed("AGENTSPEC_PODSPEC_FINDINGS"),
|
|
346
|
+
/** Virtual key the agent sends and the gateway accepts (ADR-0001); provider keys stay in the gateway. */
|
|
347
|
+
gatewayKey: fixed("AGENTSPEC_GATEWAY_KEY"),
|
|
348
|
+
/** Bind address and port the agent must honour so the sidecar can own `spec.api.port` (ADR-0028). */
|
|
349
|
+
agentHost: fixed("HOST"),
|
|
350
|
+
agentPort: fixed("PORT"),
|
|
351
|
+
/** Azure resource name the gateway config references (`$AZURE_OPENAI_RESOURCE_NAME`). */
|
|
352
|
+
azureResourceName: fixed("AZURE_OPENAI_RESOURCE_NAME")
|
|
353
|
+
}).strict().prefault({}),
|
|
354
|
+
/** Provider base-URL env vars, keyed by spec.model.provider. */
|
|
355
|
+
providerBaseUrlEnv: z.object({
|
|
356
|
+
openai: fixed("OPENAI_BASE_URL"),
|
|
357
|
+
anthropic: fixed("ANTHROPIC_BASE_URL")
|
|
358
|
+
}).strict().prefault({}),
|
|
359
|
+
paths: z.object({
|
|
360
|
+
manifestDir: fixed("/manifest"),
|
|
361
|
+
manifestFile: fixed("/manifest/agent.yaml"),
|
|
362
|
+
/** SQLite file the gateway keeps USD budget usage in; must be on a writable volume. */
|
|
363
|
+
gatewayDatabase: fixed("/gateway-data/agentgateway.db"),
|
|
364
|
+
/** Directory the init container renders the gateway config into (ADR-0025). */
|
|
365
|
+
gatewayConfigDir: fixed("/gateway"),
|
|
366
|
+
gatewayConfigFile: fixed("/gateway/config.yaml"),
|
|
367
|
+
/** Sidecar bundle inside its image; `node <entrypoint> gateway-config …` is the init container's command (ADR-0025). */
|
|
368
|
+
sidecarEntrypoint: fixed("dist/index.js"),
|
|
369
|
+
gatewayDataDir: fixed("/gateway-data")
|
|
370
|
+
}).strict().prefault({}),
|
|
371
|
+
images: z.object({
|
|
372
|
+
sidecar: fixed("ghcr.io/agents-oss/agentspec-sidecar:latest"),
|
|
373
|
+
/** agentgateway, pinned (ADR-0025). */
|
|
374
|
+
gateway: fixed("cr.agentgateway.dev/agentgateway:v1.6.0")
|
|
375
|
+
}).strict().prefault({}),
|
|
376
|
+
ports: z.object({
|
|
377
|
+
agentDefault: fixed(8e3),
|
|
378
|
+
/** Loopback port the agent binds once the sidecar takes over its declared port (ADR-0028). */
|
|
379
|
+
agentBind: fixed(18e3),
|
|
380
|
+
proxy: fixed(4e3),
|
|
381
|
+
controlPlane: fixed(4001),
|
|
382
|
+
/** agentgateway LLM listener on the pod loopback (ADR-0025). */
|
|
383
|
+
gateway: fixed(4002),
|
|
384
|
+
/** agentgateway's default stats and readiness listeners: wildcard-bound, not the agent's (ADR-0025). */
|
|
385
|
+
gatewayStats: fixed(15020),
|
|
386
|
+
gatewayReadiness: fixed(15021)
|
|
387
|
+
}).strict().prefault({}),
|
|
388
|
+
/** Bare paths served by the sidecar on the control-plane port (ADR-0023). */
|
|
389
|
+
sidecarPaths: z.object({
|
|
390
|
+
healthReady: fixed("/health/ready"),
|
|
391
|
+
gap: fixed("/gap"),
|
|
392
|
+
explore: fixed("/explore"),
|
|
393
|
+
proof: fixed("/proof"),
|
|
394
|
+
traces: fixed("/v1/traces"),
|
|
395
|
+
/** Read-only GET of the buffered, already redacted spans the gateway copied to the sidecar. */
|
|
396
|
+
spans: fixed("/spans")
|
|
397
|
+
}).strict().prefault({}),
|
|
398
|
+
/** Bare paths an agent serves itself (SDK `/agentspec/health`); the sidecar probes them on the upstream. */
|
|
399
|
+
agentPaths: z.object({
|
|
400
|
+
health: fixed("/agentspec/health")
|
|
401
|
+
}).strict().prefault({}),
|
|
402
|
+
/** Control plane API routes shared by the CLI, the sidecar push and the control plane; `{name}` is the registered agent name. */
|
|
403
|
+
controlPlanePaths: z.object({
|
|
404
|
+
/** POST: registers an agent and returns its per-agent token. */
|
|
405
|
+
register: fixed("/api/v1/register"),
|
|
406
|
+
/** POST: the SDK push-mode heartbeat, authenticated with the agent token from `register`. */
|
|
407
|
+
heartbeat: fixed("/api/v1/heartbeat"),
|
|
408
|
+
declaredAudit: fixed("/api/v1/agents/{name}/declared-audit"),
|
|
409
|
+
/** POST: the sidecar's declared audit (at start and on a manifest hash change) and its own evidence records (ADR-0008). */
|
|
410
|
+
sidecarPush: fixed("/api/v1/agents/{name}/sidecar-push"),
|
|
411
|
+
/** GET: the latest stored EvidenceRecord per (ruleId, checkId, source) of an agent, as `{ records }`; read by the mcp-server. */
|
|
412
|
+
evidence: fixed("/api/v1/agents/{name}/evidence")
|
|
413
|
+
}).strict().prefault({}),
|
|
414
|
+
/** Names inside the pod patch that every injection path must use (ADR-0028). */
|
|
415
|
+
podPatch: z.object({
|
|
416
|
+
sidecarContainer: fixed("agentspec-sidecar"),
|
|
417
|
+
/** Pod annotation the webhook writes its PodSpec findings to (JSON list of `{code, subject, message}`). */
|
|
418
|
+
podspecFindingsAnnotation: fixed("agentspec.io/podspec-findings"),
|
|
419
|
+
/** Pod annotation naming the agent; the webhook reads the manifest ConfigMap `<name>-manifest` from it, and `--deploy k8s` writes it. */
|
|
420
|
+
agentNameAnnotation: fixed("agentspec.io/agent-name"),
|
|
421
|
+
manifestVolume: fixed("agentspec-manifest"),
|
|
422
|
+
proxyPortName: fixed("proxy"),
|
|
423
|
+
controlPortName: fixed("control"),
|
|
424
|
+
gatewayContainer: fixed("agentspec-gateway"),
|
|
425
|
+
gatewayConfigInitContainer: fixed("agentspec-gateway-config"),
|
|
426
|
+
/** Sidecar subcommand the init container runs: `node <entrypoint> <this> <manifest> --out <path>`. */
|
|
427
|
+
gatewayConfigCommand: fixed("gateway-config"),
|
|
428
|
+
gatewayConfigVolume: fixed("agentspec-gateway-config"),
|
|
429
|
+
gatewayDataVolume: fixed("agentspec-gateway-data"),
|
|
430
|
+
/** Secret `<metadata.name><suffix>` holding the `sidecarToken` from `POST /api/v1/register`; the webhook gives it to the sidecar only, as `env.agentKey`, when a control plane URL is set. */
|
|
431
|
+
agentTokenSecretSuffix: fixed("-agentspec-token"),
|
|
432
|
+
agentTokenSecretKey: fixed("token"),
|
|
433
|
+
/** Loopback address the agent and sidecar reach each other and the gateway on. */
|
|
434
|
+
loopback: fixed("127.0.0.1"),
|
|
435
|
+
/** Gateway container sizing (ADR-0025): request 25m/32Mi, limit 128Mi. */
|
|
436
|
+
gatewayCpuRequest: fixed("25m"),
|
|
437
|
+
gatewayMemoryRequest: fixed("32Mi"),
|
|
438
|
+
gatewayMemoryLimit: fixed("128Mi")
|
|
439
|
+
}).strict().prefault({}),
|
|
440
|
+
/** Admission webhook the operator serves (ADR-0028). */
|
|
441
|
+
webhook: z.object({
|
|
442
|
+
/** Path kube-apiserver posts to; kopf routes `POST /<handler id>`, so this is the handler id with a leading slash. Hyphenated: kube-apiserver rejects an underscore in a service path segment (RFC 1123). */
|
|
443
|
+
injectPath: fixed("/inject-sidecar"),
|
|
444
|
+
/** Namespace label that selects the namespaces whose pods are injected. */
|
|
445
|
+
namespaceLabel: fixed("agentspec.io/enabled")
|
|
446
|
+
}).strict().prefault({}),
|
|
447
|
+
/** Known `EvidenceRecord.reason.code` values (ADR-0006). */
|
|
448
|
+
reasonCodes: z.array(z.string()).default(REASON_CODES),
|
|
449
|
+
/** Severity weights for coverage and the verified score (ADR-0007). */
|
|
450
|
+
severityWeights: z.object({
|
|
451
|
+
critical: fixed(4),
|
|
452
|
+
high: fixed(3),
|
|
453
|
+
medium: fixed(2),
|
|
454
|
+
low: fixed(1),
|
|
455
|
+
info: fixed(0)
|
|
456
|
+
}).strict().prefault({}),
|
|
457
|
+
/** Minimum verified percentage per grade; below `D` is F (ADR-0007). */
|
|
458
|
+
gradeBands: z.object({ A: fixed(90), B: fixed(75), C: fixed(60), D: fixed(45) }).strict().prefault({}),
|
|
459
|
+
/** Severity-weighted coverage percentage below which no grade is shown (ADR-0007). */
|
|
460
|
+
coverageThreshold: fixed(60),
|
|
461
|
+
/** Rule evidence registry: what can prove each audit rule (ADR-0040). */
|
|
462
|
+
ruleEvidence: z.record(z.string(), RuleEvidenceEntry).default(RULE_EVIDENCE),
|
|
463
|
+
/** Evidence point → target → the rule its records serve; each rule's registry entry lists a source for that point. */
|
|
464
|
+
evidencePoints: z.record(z.string(), z.record(z.string(), z.string())).default({
|
|
465
|
+
guardrail: { input: "SEC-LLM-01", output: "SEC-LLM-02" },
|
|
466
|
+
tool: { local: "TOOL-01" },
|
|
467
|
+
mcpClient: { "tools/list": "SEC-LLM-07", "tools/call": "TOOL-01" },
|
|
468
|
+
memoryWrite: { scrub: "MEM-01", ttl: "MEM-02", audit: "MEM-03" },
|
|
469
|
+
vectorStore: { namespace: "MEM-04" },
|
|
470
|
+
logging: { json: "OBS-02" }
|
|
471
|
+
}),
|
|
472
|
+
/** Records an evidence point aggregate keeps per window. */
|
|
473
|
+
evidencePointRecordLimit: fixed(MAX_POINT_RECORDS),
|
|
474
|
+
/** A heartbeat above this is trimmed to counts before it is sent. */
|
|
475
|
+
heartbeatMaxBytes: fixed(64 * 1024),
|
|
476
|
+
/** OTLP: resource attributes every exported span carries, and the standard endpoint env var. */
|
|
477
|
+
otlp: z.object({
|
|
478
|
+
resourceAgentName: fixed("agentspec.agent.name"),
|
|
479
|
+
resourceManifestSha256: fixed("agentspec.manifest.sha256"),
|
|
480
|
+
endpointEnv: fixed("OTEL_EXPORTER_OTLP_ENDPOINT"),
|
|
481
|
+
/** Resource attribute naming the span's producer, and the value agentgateway exports (its default); only such spans are gateway evidence. */
|
|
482
|
+
resourceServiceName: fixed("service.name"),
|
|
483
|
+
gatewayServiceName: fixed("agentgateway")
|
|
484
|
+
}).strict().prefault({})
|
|
485
|
+
}).strict();
|
|
486
|
+
var CONTRACT = ContractSchema.parse({});
|
|
487
|
+
|
|
488
|
+
// src/runtime/evidence-points.ts
|
|
489
|
+
var GUARDRAIL = EvidencePoint.enum.guardrail;
|
|
490
|
+
var [MCP_LIST, MCP_CALL] = Object.keys(CONTRACT.evidencePoints.mcpClient);
|
|
491
|
+
var [SCRUB, TTL, AUDIT] = Object.keys(CONTRACT.evidencePoints.memoryWrite);
|
|
492
|
+
var [NAMESPACE] = Object.keys(CONTRACT.evidencePoints.vectorStore);
|
|
493
|
+
var [TOOL_TARGET] = Object.keys(CONTRACT.evidencePoints.tool);
|
|
494
|
+
var [LOGGING_TARGET] = Object.keys(CONTRACT.evidencePoints.logging);
|
|
495
|
+
var keyOf = (point2, target) => `${point2}\0${target}`;
|
|
496
|
+
var DEFAULT_KEY = /* @__PURE__ */ Symbol.for("agentspec.runtime.defaultEvidencePoints");
|
|
497
|
+
var defaults = globalThis;
|
|
498
|
+
var rec = (value) => value && typeof value === "object" ? value : {};
|
|
499
|
+
var stdioServers = (spec) => (Array.isArray(rec(spec.mcp).servers) ? rec(spec.mcp).servers : []).filter((s) => s?.transport === "stdio");
|
|
500
|
+
var isDeclared = (value) => Array.isArray(value) ? value.length > 0 : Boolean(value);
|
|
501
|
+
function memoryWriteTargets(memory) {
|
|
502
|
+
const hygiene = rec(memory.hygiene);
|
|
503
|
+
const targets = /* @__PURE__ */ new Set();
|
|
504
|
+
if (isDeclared(hygiene.piiScrubFields)) targets.add(SCRUB);
|
|
505
|
+
if ([rec(memory.shortTerm).ttlSeconds, rec(memory.longTerm).ttlDays].some((ttl) => ttl !== void 0 && ttl !== null)) targets.add(TTL);
|
|
506
|
+
if (memory.longTerm && hygiene.auditLog === true) targets.add(AUDIT);
|
|
507
|
+
return targets;
|
|
508
|
+
}
|
|
509
|
+
function declaredTargets(spec) {
|
|
510
|
+
const all = (point2, declared2) => new Set(declared2 ? Object.keys(CONTRACT.evidencePoints[point2] ?? {}) : []);
|
|
511
|
+
const memory = rec(spec.memory);
|
|
512
|
+
const logging = rec(rec(spec.observability).logging);
|
|
513
|
+
return {
|
|
514
|
+
[EvidencePoint.enum.memoryWrite]: memoryWriteTargets(memory),
|
|
515
|
+
[EvidencePoint.enum.vectorStore]: new Set(rec(memory.vector).namespace ? [NAMESPACE] : []),
|
|
516
|
+
[GUARDRAIL]: new Set(Object.keys(CONTRACT.evidencePoints[GUARDRAIL] ?? {}).filter((t) => isDeclared(rec(spec.guardrails)[t]))),
|
|
517
|
+
[EvidencePoint.enum.tool]: all(EvidencePoint.enum.tool, (Array.isArray(spec.tools) ? spec.tools : []).some((t) => t?.type === "function")),
|
|
518
|
+
[EvidencePoint.enum.mcpClient]: all(EvidencePoint.enum.mcpClient, stdioServers(spec).length > 0),
|
|
519
|
+
[EvidencePoint.enum.logging]: all(EvidencePoint.enum.logging, rec(spec.observability).logging !== void 0 && logging.structured !== false)
|
|
520
|
+
};
|
|
521
|
+
}
|
|
522
|
+
function applicablePoints(spec) {
|
|
523
|
+
const declared2 = declaredTargets(spec);
|
|
524
|
+
const applicable = /* @__PURE__ */ new Map();
|
|
525
|
+
for (const [point2, targets] of Object.entries(CONTRACT.evidencePoints)) {
|
|
526
|
+
for (const [target, ruleId] of Object.entries(targets)) {
|
|
527
|
+
const listed = CONTRACT.ruleEvidence[ruleId]?.sources.some((s) => s.point === point2);
|
|
528
|
+
if (listed && declared2[point2]?.has(target)) applicable.set(keyOf(point2, target), { point: EvidencePoint.parse(point2), target, ruleId });
|
|
529
|
+
}
|
|
530
|
+
}
|
|
531
|
+
return applicable;
|
|
532
|
+
}
|
|
533
|
+
function createEvidencePoints(manifest) {
|
|
534
|
+
const manifestSha256 = canonicalManifestSha256(manifest);
|
|
535
|
+
const spec = rec(rec(manifest).spec);
|
|
536
|
+
const applicable = applicablePoints(spec);
|
|
537
|
+
const mcpServers = stdioServers(spec).map((s) => String(s.name));
|
|
538
|
+
const wired = /* @__PURE__ */ new Set();
|
|
539
|
+
const emptyWindow = () => new Map([...applicable.keys()].map((k) => [k, { total: 0, counts: { pass: 0, fail: 0, not_verifiable: 0 }, last: [] }]));
|
|
540
|
+
let calls = emptyWindow();
|
|
541
|
+
let windowStart = /* @__PURE__ */ new Date();
|
|
542
|
+
let seq = 0;
|
|
543
|
+
const shippedUpTo = /* @__PURE__ */ new WeakMap();
|
|
544
|
+
const points = {
|
|
545
|
+
register: (point2, target) => {
|
|
546
|
+
wired.add(keyOf(point2, target));
|
|
547
|
+
},
|
|
548
|
+
applies: (point2, target) => applicable.has(keyOf(point2, target)),
|
|
549
|
+
memorySpec: () => rec(spec.memory),
|
|
550
|
+
declaredMcpServers: () => [...mcpServers],
|
|
551
|
+
recordCall: (point2, target, { subject, status = "pass", reason } = {}) => {
|
|
552
|
+
if (status !== "pass" && !reason) throw new Error(`recordCall: a ${status} call of ${point2}:${target} needs a reason`);
|
|
553
|
+
const c = calls.get(keyOf(point2, target));
|
|
554
|
+
if (!c) return;
|
|
555
|
+
c.total += 1;
|
|
556
|
+
c.counts[status] += 1;
|
|
557
|
+
c.last.push({ at: /* @__PURE__ */ new Date(), seq: ++seq, subject, status, reason });
|
|
558
|
+
if (c.last.length > CONTRACT.evidencePointRecordLimit) c.last.shift();
|
|
559
|
+
},
|
|
560
|
+
snapshot: (ttlSeconds, reset = true) => {
|
|
561
|
+
const windowEnd = /* @__PURE__ */ new Date();
|
|
562
|
+
const lastSeq = /* @__PURE__ */ new Map();
|
|
563
|
+
const window = { start: windowStart.toISOString(), end: windowEnd.toISOString() };
|
|
564
|
+
const aggregates = [...applicable].map(([key, { point: point2, target, ruleId }]) => {
|
|
565
|
+
const c = calls.get(key);
|
|
566
|
+
const state = c.total ? "fired" : wired.has(key) ? "wired" : "not_wired";
|
|
567
|
+
lastSeq.set(key, seq);
|
|
568
|
+
const records = c.last.map(({ at, subject, status, reason }) => ({
|
|
569
|
+
checkId: subject ?? `${point2}:${target}`,
|
|
570
|
+
ruleId,
|
|
571
|
+
status: EvidenceStatus.enum[status],
|
|
572
|
+
...reason ? { reason } : {},
|
|
573
|
+
source: EvidenceSource.enum["sdk-observed"],
|
|
574
|
+
origin: EvidenceOrigin.enum.in_process,
|
|
575
|
+
collector: Collector.enum.sdk,
|
|
576
|
+
observedAt: at.toISOString(),
|
|
577
|
+
window,
|
|
578
|
+
ttlSeconds,
|
|
579
|
+
sampleSize: c.total,
|
|
580
|
+
traceIds: [],
|
|
581
|
+
manifestSha256
|
|
582
|
+
}));
|
|
583
|
+
return { point: point2, target, state, counts: { ...c.counts }, records };
|
|
584
|
+
});
|
|
585
|
+
if (reset) {
|
|
586
|
+
calls = emptyWindow();
|
|
587
|
+
windowStart = windowEnd;
|
|
588
|
+
} else {
|
|
589
|
+
shippedUpTo.set(aggregates, { lastSeq, windowEnd });
|
|
590
|
+
}
|
|
591
|
+
return aggregates;
|
|
592
|
+
},
|
|
593
|
+
subtract: (shipped) => {
|
|
594
|
+
const taken = shippedUpTo.get(shipped);
|
|
595
|
+
if (!taken) throw new Error("EvidencePoints.subtract: pass the array snapshot() returned");
|
|
596
|
+
for (const a of shipped) {
|
|
597
|
+
const key = keyOf(a.point, a.target);
|
|
598
|
+
const c = calls.get(key);
|
|
599
|
+
c.total -= a.counts.pass + a.counts.fail + a.counts.not_verifiable;
|
|
600
|
+
for (const status of ["pass", "fail", "not_verifiable"]) c.counts[status] -= a.counts[status];
|
|
601
|
+
c.last = c.last.filter((l) => l.seq > taken.lastSeq.get(key));
|
|
602
|
+
}
|
|
603
|
+
windowStart = taken.windowEnd;
|
|
604
|
+
}
|
|
605
|
+
};
|
|
606
|
+
defaults[DEFAULT_KEY] = points;
|
|
607
|
+
return points;
|
|
608
|
+
}
|
|
609
|
+
function defaultPoints(name) {
|
|
610
|
+
const points = defaults[DEFAULT_KEY];
|
|
611
|
+
if (!points) throw new Error(`${name}: no evidence points exist yet \u2014 create them first (createEvidencePoints(manifest))`);
|
|
612
|
+
return points;
|
|
613
|
+
}
|
|
614
|
+
function guardrail(fn, options, points = defaultPoints("guardrail")) {
|
|
615
|
+
const valid = Object.keys(CONTRACT.evidencePoints[GUARDRAIL] ?? {});
|
|
616
|
+
const { direction } = options;
|
|
617
|
+
if (!valid.includes(direction)) {
|
|
618
|
+
throw new Error(`guardrail: unknown direction '${direction}'; use one of ${valid.join(", ")}`);
|
|
619
|
+
}
|
|
620
|
+
points.register(GUARDRAIL, direction);
|
|
621
|
+
return function(...args) {
|
|
622
|
+
points.recordCall(GUARDRAIL, direction);
|
|
623
|
+
return fn.apply(this, args);
|
|
624
|
+
};
|
|
625
|
+
}
|
|
626
|
+
|
|
627
|
+
// src/health/tool-check-id.ts
|
|
628
|
+
function slugify(s) {
|
|
629
|
+
return s.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
|
|
630
|
+
}
|
|
631
|
+
|
|
632
|
+
// src/runtime/call-points.ts
|
|
633
|
+
var { tool: TOOL, mcpClient: MCP_CLIENT, logging: LOGGING } = EvidencePoint.enum;
|
|
634
|
+
function tool(fn, options, points = defaultPoints("tool")) {
|
|
635
|
+
points.register(TOOL, TOOL_TARGET);
|
|
636
|
+
const subject = `${TOOL}:${slugify(options.name)}`;
|
|
637
|
+
return function(...args) {
|
|
638
|
+
points.recordCall(TOOL, TOOL_TARGET, { subject });
|
|
639
|
+
return fn.apply(this, args);
|
|
640
|
+
};
|
|
641
|
+
}
|
|
642
|
+
var calledToolName = (arg) => typeof arg === "string" ? arg : String(arg?.name);
|
|
643
|
+
function mcpClient(session, options, points = defaultPoints("mcpClient")) {
|
|
644
|
+
const declared2 = points.declaredMcpServers();
|
|
645
|
+
if (!declared2.includes(options.server)) {
|
|
646
|
+
throw new Error(`mcpClient: '${options.server}' is not a stdio server in spec.mcp.servers; declared: ${declared2.join(", ") || "none"}`);
|
|
647
|
+
}
|
|
648
|
+
points.register(MCP_CLIENT, MCP_LIST);
|
|
649
|
+
points.register(MCP_CLIENT, MCP_CALL);
|
|
650
|
+
const recorded = {
|
|
651
|
+
listTools: () => points.recordCall(MCP_CLIENT, MCP_LIST, { subject: `mcp:${options.server}:${MCP_LIST}` }),
|
|
652
|
+
callTool: (args) => points.recordCall(MCP_CLIENT, MCP_CALL, { subject: `mcp:${options.server}:${MCP_CALL}:${calledToolName(args[0])}` })
|
|
653
|
+
};
|
|
654
|
+
return new Proxy(session, {
|
|
655
|
+
get(target, prop, receiver) {
|
|
656
|
+
const member = Reflect.get(target, prop, receiver);
|
|
657
|
+
const record = typeof prop === "string" && Object.hasOwn(recorded, prop) ? recorded[prop] : void 0;
|
|
658
|
+
if (!record || typeof member !== "function") return member;
|
|
659
|
+
return (...args) => {
|
|
660
|
+
record(args);
|
|
661
|
+
return member.apply(target, args);
|
|
662
|
+
};
|
|
663
|
+
}
|
|
664
|
+
});
|
|
665
|
+
}
|
|
666
|
+
function structuredLogging(options = {}, points = defaultPoints("structuredLogging")) {
|
|
667
|
+
const name = options.name ?? "root";
|
|
668
|
+
const write = options.write ?? ((line) => {
|
|
669
|
+
process.stdout.write(`${line}
|
|
670
|
+
`);
|
|
671
|
+
});
|
|
672
|
+
points.register(LOGGING, LOGGING_TARGET);
|
|
673
|
+
const log = (level, message, fields) => {
|
|
674
|
+
write(JSON.stringify({ ...fields, time: (/* @__PURE__ */ new Date()).toISOString(), level: level.toUpperCase(), logger: name, message }));
|
|
675
|
+
points.recordCall(LOGGING, LOGGING_TARGET, { subject: `${LOGGING}:${name}` });
|
|
676
|
+
};
|
|
677
|
+
return {
|
|
678
|
+
log,
|
|
679
|
+
debug: (m, f) => log("debug", m, f),
|
|
680
|
+
info: (m, f) => log("info", m, f),
|
|
681
|
+
warn: (m, f) => log("warn", m, f),
|
|
682
|
+
error: (m, f) => log("error", m, f)
|
|
683
|
+
};
|
|
684
|
+
}
|
|
685
|
+
var { memoryWrite: MEMORY_WRITE, vectorStore: VECTOR_STORE } = EvidencePoint.enum;
|
|
686
|
+
var REDACTED = "[REDACTED]";
|
|
687
|
+
var TTL_APPLIED = "applied";
|
|
688
|
+
var TTL_PASSED_THROUGH = "passed-through";
|
|
689
|
+
var TTL_UNSUPPORTED = "unsupported";
|
|
690
|
+
var NOT_VERIFIABLE_CODE = "instrumentation_unavailable";
|
|
691
|
+
var WRONG_NAMESPACE_CODE = "undeclared_namespace";
|
|
692
|
+
var NO_NAMESPACE_CODE = "no_evidence";
|
|
693
|
+
for (const code of [NOT_VERIFIABLE_CODE, WRONG_NAMESPACE_CODE, NO_NAMESPACE_CODE]) {
|
|
694
|
+
if (!CONTRACT.reasonCodes.includes(code)) throw new Error(`contract.reasonCodes lacks '${code}'`);
|
|
695
|
+
}
|
|
696
|
+
var PATTERNS = {
|
|
697
|
+
email: /[\w.+-]+@[\w-]+(?:\.[\w-]+)+/g,
|
|
698
|
+
ssn: /\b\d{3}-\d{2}-\d{4}\b/g,
|
|
699
|
+
credit_card: /\b(?:\d[ -]?){13,16}\b/g,
|
|
700
|
+
iban: /\b[A-Z]{2}\d{2}[A-Z0-9]{11,30}\b/g,
|
|
701
|
+
phone_number: /\+\d[\d ().-]{7,}\d|\(?\b\d{3}\)?[ .-]\d{3}[ .-]\d{4}\b/g,
|
|
702
|
+
// an international +, or a 3-3-4 layout: not dates or ids
|
|
703
|
+
ip_address: /\b(?:\d{1,3}\.){3}\d{1,3}\b/g
|
|
704
|
+
};
|
|
705
|
+
var isContainer = (node) => typeof node === "object" && node !== null && !(node instanceof Date) && !(node instanceof Error) && !(node instanceof RegExp) && !(node instanceof URL) && !(node instanceof Map) && !(node instanceof Set) && !ArrayBuffer.isView(node);
|
|
706
|
+
function scrub(value, fields, byValue = true) {
|
|
707
|
+
const wanted = new Set(fields.map((f) => f.toLowerCase()));
|
|
708
|
+
const patterns = byValue ? Object.entries(PATTERNS).filter(([name]) => wanted.has(name)).map(([, p]) => p) : [];
|
|
709
|
+
const path = /* @__PURE__ */ new WeakSet();
|
|
710
|
+
const walk = (node, declared2) => {
|
|
711
|
+
if (typeof node === "object" && node !== null && path.has(node)) return [node, 0];
|
|
712
|
+
if (typeof node === "object" && node !== null) {
|
|
713
|
+
path.add(node);
|
|
714
|
+
try {
|
|
715
|
+
return walkNode(node, declared2);
|
|
716
|
+
} finally {
|
|
717
|
+
path.delete(node);
|
|
718
|
+
}
|
|
719
|
+
}
|
|
720
|
+
return walkNode(node, declared2);
|
|
721
|
+
};
|
|
722
|
+
const walkNode = (node, declared2) => {
|
|
723
|
+
if (Array.isArray(node)) {
|
|
724
|
+
const walked = node.map((child) => walk(child, declared2));
|
|
725
|
+
return [walked.map((w) => w[0]), walked.reduce((n, w) => n + w[1], 0)];
|
|
726
|
+
}
|
|
727
|
+
if (isContainer(node)) {
|
|
728
|
+
const out = Object.create(Object.getPrototypeOf(node));
|
|
729
|
+
let found = 0;
|
|
730
|
+
for (const [key, child] of Object.entries(node)) {
|
|
731
|
+
const [walked, n] = walk(child, declared2 || wanted.has(key.toLowerCase()));
|
|
732
|
+
out[key] = walked;
|
|
733
|
+
found += n;
|
|
734
|
+
}
|
|
735
|
+
return [out, found];
|
|
736
|
+
}
|
|
737
|
+
if (declared2 && node !== null && node !== void 0) return [REDACTED, 1];
|
|
738
|
+
if (typeof node === "string") {
|
|
739
|
+
let found = 0;
|
|
740
|
+
let text = node;
|
|
741
|
+
for (const pattern of patterns) text = text.replace(pattern, () => {
|
|
742
|
+
found += 1;
|
|
743
|
+
return REDACTED;
|
|
744
|
+
});
|
|
745
|
+
return [text, found];
|
|
746
|
+
}
|
|
747
|
+
return [node, 0];
|
|
748
|
+
};
|
|
749
|
+
return walk(value, false);
|
|
750
|
+
}
|
|
751
|
+
var Writes = class {
|
|
752
|
+
constructor(points, kind, fields, ttlSeconds, audit) {
|
|
753
|
+
this.points = points;
|
|
754
|
+
this.kind = kind;
|
|
755
|
+
this.fields = fields;
|
|
756
|
+
this.ttlSeconds = ttlSeconds;
|
|
757
|
+
this.audit = audit;
|
|
758
|
+
}
|
|
759
|
+
points;
|
|
760
|
+
kind;
|
|
761
|
+
fields;
|
|
762
|
+
ttlSeconds;
|
|
763
|
+
audit;
|
|
764
|
+
/** The declared TTL, or the caller's own when it is shorter: a write never outlives the declared retention. */
|
|
765
|
+
static capped(requested, declared2) {
|
|
766
|
+
return requested === void 0 || requested > declared2 ? declared2 : requested;
|
|
767
|
+
}
|
|
768
|
+
scrubbed(value, byValue = true) {
|
|
769
|
+
return this.fields.length ? scrub(value, this.fields, byValue) : [value, 0];
|
|
770
|
+
}
|
|
771
|
+
/** One write: the MEM-01 record, the MEM-02 record when a TTL is declared, the audit entry and MEM-03 record. */
|
|
772
|
+
record(operation, scrubbed, ttl) {
|
|
773
|
+
const subject = `memory:${this.kind}:${operation}`;
|
|
774
|
+
this.points.recordCall(MEMORY_WRITE, SCRUB, { subject });
|
|
775
|
+
if (ttl !== void 0) {
|
|
776
|
+
const ttlSubject = `${subject}:ttl=${ttl}`;
|
|
777
|
+
if (ttl === TTL_UNSUPPORTED) {
|
|
778
|
+
this.points.recordCall(MEMORY_WRITE, TTL, { subject: ttlSubject, status: "not_verifiable", reason: { code: NOT_VERIFIABLE_CODE, detail: `the ${this.kind} backend cannot apply a TTL` } });
|
|
779
|
+
} else {
|
|
780
|
+
this.points.recordCall(MEMORY_WRITE, TTL, { subject: ttlSubject });
|
|
781
|
+
}
|
|
782
|
+
}
|
|
783
|
+
if (this.points.applies(MEMORY_WRITE, AUDIT)) {
|
|
784
|
+
this.audit(JSON.stringify({ event: "memory.write", backend: this.kind, operation, scrubbed, ttl: ttl ?? null }));
|
|
785
|
+
this.points.recordCall(MEMORY_WRITE, AUDIT, { subject });
|
|
786
|
+
}
|
|
787
|
+
}
|
|
788
|
+
};
|
|
789
|
+
var writing = new AsyncLocalStorage();
|
|
790
|
+
function proxied(backend, overrides) {
|
|
791
|
+
return new Proxy(backend, {
|
|
792
|
+
get(target, prop, receiver) {
|
|
793
|
+
const original = Reflect.get(target, prop, receiver);
|
|
794
|
+
const override = typeof prop === "string" && Object.hasOwn(overrides, prop) ? overrides[prop] : void 0;
|
|
795
|
+
if (!override || typeof original !== "function") return original;
|
|
796
|
+
return (...args) => writing.getStore() ? original.apply(receiver, args) : writing.run(true, () => override((...a) => original.apply(receiver, a), args, receiver));
|
|
797
|
+
}
|
|
798
|
+
});
|
|
799
|
+
}
|
|
800
|
+
var takesTtl = (backend, fn, base) => backend.supportsTtl === true && typeof fn === "function" && fn.length > base;
|
|
801
|
+
function checkpointerProxy(backend, writes) {
|
|
802
|
+
const prepare = (method, base, args) => {
|
|
803
|
+
if (writes.ttlSeconds === void 0) return void 0;
|
|
804
|
+
if (writes.ttlSeconds === 0) return TTL_UNSUPPORTED;
|
|
805
|
+
if (!takesTtl(backend, backend[method], base)) return TTL_UNSUPPORTED;
|
|
806
|
+
args[base] = Writes.capped(args[base], writes.ttlSeconds);
|
|
807
|
+
return TTL_PASSED_THROUGH;
|
|
808
|
+
};
|
|
809
|
+
return proxied(backend, {
|
|
810
|
+
put: (original, args) => {
|
|
811
|
+
const [config, checkpoint, metadata, versions] = args;
|
|
812
|
+
const key = "channelValues" in checkpoint && !("channel_values" in checkpoint) ? "channelValues" : "channel_values";
|
|
813
|
+
const [values, n] = writes.scrubbed(checkpoint[key]);
|
|
814
|
+
const [meta, m] = writes.scrubbed(metadata, false);
|
|
815
|
+
const next = [config, key in checkpoint ? { ...checkpoint, [key]: values } : checkpoint, meta, versions, ...args.slice(4)];
|
|
816
|
+
const ttl = prepare("put", 4, next);
|
|
817
|
+
return Promise.resolve(original(...next)).then((result) => {
|
|
818
|
+
writes.record("put", n + m, ttl);
|
|
819
|
+
return result;
|
|
820
|
+
});
|
|
821
|
+
},
|
|
822
|
+
putWrites: (original, args) => {
|
|
823
|
+
const [config, pending, taskId] = args;
|
|
824
|
+
const scrubbed = pending.map(([channel, value]) => {
|
|
825
|
+
const [one, n] = writes.scrubbed({ [channel]: value });
|
|
826
|
+
return [[channel, one[channel]], n];
|
|
827
|
+
});
|
|
828
|
+
const next = [config, scrubbed.map(([w]) => w), taskId, ...args.slice(3)];
|
|
829
|
+
const ttl = prepare("putWrites", 3, next);
|
|
830
|
+
return Promise.resolve(original(...next)).then((result) => {
|
|
831
|
+
writes.record("put_writes", scrubbed.reduce((n, [, c]) => n + c, 0), ttl);
|
|
832
|
+
return result;
|
|
833
|
+
});
|
|
834
|
+
}
|
|
835
|
+
});
|
|
836
|
+
}
|
|
837
|
+
function storeProxy(backend, writes) {
|
|
838
|
+
const prepare = (ops) => {
|
|
839
|
+
const puts = [];
|
|
840
|
+
const prepared = ops.map((op) => {
|
|
841
|
+
if (op?.value === void 0 || op.value === null) return op;
|
|
842
|
+
const [value, n] = writes.scrubbed(op.value);
|
|
843
|
+
let ttl;
|
|
844
|
+
const next = { ...op, value };
|
|
845
|
+
if (writes.ttlSeconds !== void 0) {
|
|
846
|
+
const supported = Boolean(backend.supportsTtl) && writes.ttlSeconds > 0;
|
|
847
|
+
if (supported) next.ttl = Writes.capped(op.ttl ?? void 0, writes.ttlSeconds / 60);
|
|
848
|
+
ttl = supported ? TTL_APPLIED : TTL_UNSUPPORTED;
|
|
849
|
+
}
|
|
850
|
+
puts.push([n, ttl]);
|
|
851
|
+
return Object.setPrototypeOf(next, Object.getPrototypeOf(op));
|
|
852
|
+
});
|
|
853
|
+
return { prepared, puts };
|
|
854
|
+
};
|
|
855
|
+
return proxied(backend, {
|
|
856
|
+
batch: (original, [ops, ...rest]) => {
|
|
857
|
+
const { prepared, puts } = prepare(ops);
|
|
858
|
+
return Promise.resolve(original(prepared, ...rest)).then((result) => {
|
|
859
|
+
for (const [n, ttl] of puts) writes.record("put", n, ttl);
|
|
860
|
+
return result;
|
|
861
|
+
});
|
|
862
|
+
}
|
|
863
|
+
});
|
|
864
|
+
}
|
|
865
|
+
function memoryWrite(backend, options = {}, points = defaultPoints("memoryWrite")) {
|
|
866
|
+
const memory = points.memorySpec();
|
|
867
|
+
const fields = memory.hygiene?.piiScrubFields ?? [];
|
|
868
|
+
const audit = options.audit ?? ((entry) => console.info(entry));
|
|
869
|
+
const has = (name) => typeof backend[name] === "function";
|
|
870
|
+
let writes;
|
|
871
|
+
let wrapped;
|
|
872
|
+
if (has("putWrites")) {
|
|
873
|
+
writes = new Writes(points, "checkpointer", fields, memory.shortTerm?.ttlSeconds ?? void 0, audit);
|
|
874
|
+
wrapped = checkpointerProxy(backend, writes);
|
|
875
|
+
} else if (has("batch")) {
|
|
876
|
+
const days = memory.longTerm?.ttlDays;
|
|
877
|
+
writes = new Writes(points, "store", fields, days == null ? void 0 : days * 24 * 60 * 60, audit);
|
|
878
|
+
wrapped = storeProxy(backend, writes);
|
|
879
|
+
} else {
|
|
880
|
+
throw new Error("memoryWrite: the backend is neither a checkpointer (putWrites) nor a Store (batch)");
|
|
881
|
+
}
|
|
882
|
+
for (const target of Object.keys(CONTRACT.evidencePoints[MEMORY_WRITE])) points.register(MEMORY_WRITE, target);
|
|
883
|
+
return wrapped;
|
|
884
|
+
}
|
|
885
|
+
var POSITIONAL = /* @__PURE__ */ Symbol("positional namespace");
|
|
886
|
+
function usedNamespace(args, bound) {
|
|
887
|
+
for (const arg of args) {
|
|
888
|
+
if (arg && typeof arg === "object" && "namespace" in arg) return arg.namespace;
|
|
889
|
+
}
|
|
890
|
+
return bound !== void 0 && args.some((a) => typeof a === "string") ? POSITIONAL : bound;
|
|
891
|
+
}
|
|
892
|
+
function vectorStore(client, options = {}, points = defaultPoints("vectorStore")) {
|
|
893
|
+
const declared2 = points.memorySpec().vector?.namespace;
|
|
894
|
+
points.register(VECTOR_STORE, NAMESPACE);
|
|
895
|
+
const record = (used) => {
|
|
896
|
+
if (used === POSITIONAL) {
|
|
897
|
+
points.recordCall(VECTOR_STORE, NAMESPACE, { status: "not_verifiable", reason: { code: NO_NAMESPACE_CODE, detail: "a string argument may name another namespace; pass { namespace } to the call" } });
|
|
898
|
+
} else if (used === void 0) {
|
|
899
|
+
points.recordCall(VECTOR_STORE, NAMESPACE, { status: "not_verifiable", reason: { code: NO_NAMESPACE_CODE, detail: "the call names no namespace; bind the client to one" } });
|
|
900
|
+
} else if (used === declared2) {
|
|
901
|
+
points.recordCall(VECTOR_STORE, NAMESPACE, { subject: `vector:${used}` });
|
|
902
|
+
} else {
|
|
903
|
+
points.recordCall(VECTOR_STORE, NAMESPACE, { subject: `vector:${used}`, status: "fail", reason: { code: WRONG_NAMESPACE_CODE, detail: `namespace '${used}' is not the declared '${declared2}'` } });
|
|
904
|
+
}
|
|
905
|
+
};
|
|
906
|
+
return new Proxy(client, {
|
|
907
|
+
get(target, prop, receiver) {
|
|
908
|
+
const member = Reflect.get(target, prop, receiver);
|
|
909
|
+
if (typeof prop !== "string" || prop.startsWith("_") || typeof member !== "function") return member;
|
|
910
|
+
if (prop in Object.prototype && !Object.hasOwn(target, prop)) return member;
|
|
911
|
+
return (...args) => {
|
|
912
|
+
record(usedNamespace(args, options.namespace));
|
|
913
|
+
return member.apply(target, args);
|
|
914
|
+
};
|
|
915
|
+
}
|
|
916
|
+
});
|
|
917
|
+
}
|
|
918
|
+
|
|
919
|
+
export { createEvidencePoints, guardrail, mcpClient, memoryWrite, scrub, structuredLogging, tool, vectorStore };
|
|
920
|
+
//# sourceMappingURL=runtime.js.map
|
|
921
|
+
//# sourceMappingURL=runtime.js.map
|