@withgateway/sdk 0.2.6 → 0.2.9

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 (110) hide show
  1. package/README.md +24 -8
  2. package/dist/cli.js +15468 -11263
  3. package/dist/cli.js.map +1 -1
  4. package/dist/cli.mjs +15233 -11028
  5. package/dist/cli.mjs.map +1 -1
  6. package/dist/files/index.d.mts +1 -1
  7. package/dist/files/index.d.ts +1 -1
  8. package/dist/files/index.js +291 -40
  9. package/dist/files/index.js.map +1 -1
  10. package/dist/files/index.mjs +284 -37
  11. package/dist/files/index.mjs.map +1 -1
  12. package/dist/hooks/index.d.mts +1 -1
  13. package/dist/hooks/index.d.ts +1 -1
  14. package/dist/hooks/index.js +203 -47
  15. package/dist/hooks/index.js.map +1 -1
  16. package/dist/hooks/index.mjs +198 -42
  17. package/dist/hooks/index.mjs.map +1 -1
  18. package/dist/{index-BaKu5ZSU.d.mts → index-C3UzD0G3.d.mts} +75 -1
  19. package/dist/{index-BaKu5ZSU.d.ts → index-C3UzD0G3.d.ts} +75 -1
  20. package/dist/{index-CLkMr6VG.d.ts → index-D-_4Ibcn.d.ts} +36 -4
  21. package/dist/{index-CdbmO4aX.d.mts → index-FfK4Nump.d.mts} +36 -4
  22. package/dist/index.d.mts +3 -3
  23. package/dist/index.d.ts +3 -3
  24. package/dist/index.js +2149 -615
  25. package/dist/index.js.map +1 -1
  26. package/dist/index.mjs +2053 -566
  27. package/dist/index.mjs.map +1 -1
  28. package/dist/traces/index.js +268 -31
  29. package/dist/traces/index.js.map +1 -1
  30. package/dist/traces/index.mjs +262 -28
  31. package/dist/traces/index.mjs.map +1 -1
  32. package/dist/tracing/index.js +19 -11
  33. package/dist/tracing/index.js.map +1 -1
  34. package/dist/tracing/index.mjs +19 -11
  35. package/dist/tracing/index.mjs.map +1 -1
  36. package/dist/worlds/index.d.mts +886 -117
  37. package/dist/worlds/index.d.ts +886 -117
  38. package/dist/worlds/index.js +1770 -452
  39. package/dist/worlds/index.js.map +1 -1
  40. package/dist/worlds/index.mjs +1752 -434
  41. package/dist/worlds/index.mjs.map +1 -1
  42. package/package.json +14 -10
  43. package/runtime/gatewaysdk/environment/_toml.py +3 -10
  44. package/runtime/gatewaysdk/environment/_world.py +95 -28
  45. package/runtime/gatewaysdk/environment/runtime.py +10 -6
  46. package/runtime/gatewaysdk/environment/schema/__main__.py +35 -0
  47. package/runtime/gatewaysdk/environment/schema/api.py +19 -23
  48. package/runtime/gatewaysdk/environment/schema/batch.py +68 -14
  49. package/runtime/gatewaysdk/environment/schema/bundle_runtime.py +4 -2
  50. package/runtime/gatewaysdk/environment/schema/cast.py +264 -0
  51. package/runtime/gatewaysdk/environment/schema/compiler.py +35 -1
  52. package/runtime/gatewaysdk/environment/schema/conform.py +28 -10
  53. package/runtime/gatewaysdk/environment/schema/connector.py +59 -14
  54. package/runtime/gatewaysdk/environment/schema/connectors/custom/handlers.py +38 -1
  55. package/runtime/gatewaysdk/environment/schema/connectors/google-drive/readers/merge.toml +3 -1
  56. package/runtime/gatewaysdk/environment/schema/credentials.py +20 -0
  57. package/runtime/gatewaysdk/environment/schema/csv_rows.py +117 -0
  58. package/runtime/gatewaysdk/environment/schema/cycles.py +121 -0
  59. package/runtime/gatewaysdk/environment/schema/data.py +21 -5
  60. package/runtime/gatewaysdk/environment/schema/grading.py +95 -13
  61. package/runtime/gatewaysdk/environment/schema/handler_errors.py +44 -0
  62. package/runtime/gatewaysdk/environment/schema/handler_scan.py +175 -0
  63. package/runtime/gatewaysdk/environment/schema/host.py +68 -115
  64. package/runtime/gatewaysdk/environment/schema/host_requests.py +78 -0
  65. package/runtime/gatewaysdk/environment/schema/host_surfaces.py +12 -0
  66. package/runtime/gatewaysdk/environment/schema/ingest.py +5 -18
  67. package/runtime/gatewaysdk/environment/schema/local.py +7 -10
  68. package/runtime/gatewaysdk/environment/schema/openapi_document.py +322 -0
  69. package/runtime/gatewaysdk/environment/schema/openapi_import.py +382 -0
  70. package/runtime/gatewaysdk/environment/schema/openapi_routes.py +441 -0
  71. package/runtime/gatewaysdk/environment/schema/openapi_schemas.py +629 -0
  72. package/runtime/gatewaysdk/environment/schema/openapi_source.py +210 -0
  73. package/runtime/gatewaysdk/environment/schema/platform.py +110 -299
  74. package/runtime/gatewaysdk/environment/schema/platform_import.py +182 -0
  75. package/runtime/gatewaysdk/environment/schema/platform_query.py +95 -0
  76. package/runtime/gatewaysdk/environment/schema/route_bindings.py +176 -0
  77. package/runtime/gatewaysdk/environment/schema/runtime.py +56 -7
  78. package/runtime/gatewaysdk/environment/schema/scaffold.py +64 -5
  79. package/runtime/gatewaysdk/environment/schema/skills/benchmarks-getting-started/SKILL.md +70 -22
  80. package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/SKILL.md +54 -4
  81. package/runtime/gatewaysdk/environment/schema/skills/hooks-getting-started/SKILL.md +27 -2
  82. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/ROWS.md +62 -0
  83. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/SKILL.md +91 -54
  84. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/SKILL.md +146 -146
  85. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/cli-mcp-map.md +11 -7
  86. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/gotchas.md +30 -0
  87. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/new-world-sandbox.md +43 -0
  88. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/openapi-import.md +90 -0
  89. package/runtime/gatewaysdk/environment/schema/store.py +15 -6
  90. package/runtime/gatewaysdk/environment/schema/store_contract.py +119 -0
  91. package/runtime/gatewaysdk/environment/schema/tasks.py +121 -32
  92. package/runtime/gatewaysdk/environment/schema/tools_world.py +32 -10
  93. package/runtime/gatewaysdk/environment/schema/tree_import.py +228 -0
  94. package/runtime/gatewaysdk/environment/schema/ui.py +18 -2
  95. package/runtime/gatewaysdk/environment/schema/validation.py +35 -0
  96. package/runtime/gatewaysdk/environment/schema/verbs.py +8 -2
  97. package/runtime/gatewaysdk/environment/world.py +42 -3
  98. package/runtime/gatewaysdk/environment/world_session_contract.py +57 -0
  99. package/skills/benchmarks-getting-started/SKILL.md +70 -22
  100. package/skills/connector-schema-authoring/SKILL.md +54 -4
  101. package/skills/connector-schema-authoring/connector-worlds.md +21 -7
  102. package/skills/connector-schema-authoring/world-schema.md +144 -83
  103. package/skills/hooks-getting-started/SKILL.md +27 -2
  104. package/skills/world-data-ingestion/ROWS.md +62 -0
  105. package/skills/world-data-ingestion/SKILL.md +91 -54
  106. package/skills/worlds-getting-started/SKILL.md +146 -146
  107. package/skills/worlds-getting-started/references/cli-mcp-map.md +11 -7
  108. package/skills/worlds-getting-started/references/gotchas.md +30 -0
  109. package/skills/worlds-getting-started/references/new-world-sandbox.md +43 -0
  110. package/skills/worlds-getting-started/references/openapi-import.md +90 -0
@@ -1 +1 @@
1
- export { A as Alias, a as AliasHandler, b as AliasMap, c as AuditFinding, d as AuditRecord, e as AuditReport, B as Bound, C as CONTEXT_KEY, f as CallableTool, g as CommandHandler, h as ConnectorTool, D as Decision, j as DenyHandler, E as EVENTS, k as EVENT_ALIASES, F as FieldKinds, l as FieldSource, m as FinderSource, n as Finding, o as FunctionHandler, H as HANDLER_TYPES, p as Handler, q as HandlerFn, r as HandlerSpec, s as HandlerType, t as HookConfig, u as HookConfigError, v as HookDenied, w as HookError, x as HookEvent, y as HookEventName, z as HookRequest, G as HookResponse, I as HookResult, J as HookRule, K as HookRun, L as HookRunOptions, M as HookedSession, N as HttpHandler, O as HttpTool, P as INBOUND_KINDS, Q as INPUT_TYPES, R as Identifier, S as IdentifierCensus, T as IdentifierSource, U as Identity, V as InboundKind, W as JsonSchema, X as KINDS, Y as LegendEntry, Z as LegendRow, _ as LegendSource, $ as LiveConfig, a0 as LiveTool, a1 as LiveToolError, a2 as LiveTools, a3 as Matcher, a4 as PARSE_MODES, a5 as Pair, a6 as ParseMode, a7 as RecordHandler, a8 as RecordSink, a9 as Recorder, aa as RedactHandler, ab as RedactionAudit, ac as Replay, ad as RequestFn, ae as RunVerdict, af as SeedEntity, ag as SeedRow, ah as SessionLike, ai as TOOL_KINDS, aj as ToolFn, ak as ToolFunctions, al as ToolKind, am as ToolSpec, an as WrappedTools, ao as applyLimit, ap as applyResult, aq as buildTool, ar as canonical, as as definition, at as describeHandler, au as describeMatcher, av as describeTool, aw as emailPairs, ax as emptyConfig, ay as emptyLive, az as eventToJson, aA as explodeIp, aB as findKind, aC as folded, aD as genericPairs, aE as importCallable, aF as inputSchema, aG as interpolateHeaders, aH as interpolatePath, aI as isGlobalIpv4, aJ as jsPattern, aK as jsonPath, aL as loadHookConfig, aM as mapFields, aN as matches, aO as mirrorHandle, aP as namePairs, aQ as newRunKey, aR as normalizeEvent, aS as pageTitle, aT as parseHookConfig, aU as parseJson, aV as parseMatcher, aW as parseRegex, aX as parseStdout, aY as parseText, aZ as phonePairs, a_ as pyQuote, a$ as readConnection, b0 as readable, b1 as refusalReason, b2 as render, b3 as resultFromJson, b4 as splitTopLevel, b5 as stripTags, b6 as unescapeHtml, b7 as vendorOf, b8 as withContext, b9 as withDefaults } from '../index-BaKu5ZSU.mjs';
1
+ export { A as Alias, a as AliasHandler, b as AliasMap, c as AuditFinding, d as AuditRecord, e as AuditReport, B as Bound, C as CONTEXT_KEY, f as CallableTool, g as CommandHandler, h as ConnectorTool, D as Decision, j as DenyHandler, E as EVENTS, k as EVENT_ALIASES, F as FieldKinds, l as FieldSource, m as FinderSource, n as Finding, o as FunctionHandler, H as HANDLER_TYPES, p as Handler, q as HandlerFn, r as HandlerSpec, s as HandlerType, t as HookConfig, u as HookConfigError, v as HookDenied, w as HookError, x as HookEvent, y as HookEventName, z as HookRequest, G as HookResponse, I as HookResult, J as HookRule, K as HookRun, L as HookRunOptions, M as HookedSession, N as HttpHandler, O as HttpTool, P as INBOUND_KINDS, Q as INPUT_TYPES, R as Identifier, S as IdentifierCensus, T as IdentifierSource, U as Identity, V as InboundKind, W as JsonSchema, X as KINDS, Y as LegendEntry, Z as LegendRow, _ as LegendSource, $ as LiveConfig, a0 as LiveTool, a1 as LiveToolError, a2 as LiveTools, a3 as Matcher, a4 as PARSE_MODES, a5 as Pair, a6 as ParseMode, a7 as RecordHandler, a8 as RecordSink, a9 as Recorder, aa as RedactHandler, ab as RedactionAudit, ac as Replay, ad as RequestFn, ae as RunVerdict, af as SeedEntity, ag as SeedRow, ah as SessionLike, ai as TOOL_KINDS, aj as ToolFn, ak as ToolFunctions, al as ToolKind, am as ToolSpec, an as WrappedTools, ao as applyLimit, ap as applyResult, aq as buildTool, ar as canonical, as as definition, at as describeHandler, au as describeMatcher, av as describeTool, aw as emailPairs, ax as emptyConfig, ay as emptyLive, az as eventToJson, aA as explodeIp, aB as findKind, aC as folded, aD as genericPairs, aE as importCallable, aF as inputSchema, aG as interpolateHeaders, aH as interpolatePath, aI as isGlobalIpv4, aJ as jsPattern, aK as jsonPath, aL as loadHookConfig, aM as mapFields, aN as matches, aO as mirrorHandle, aP as namePairs, aQ as newRunKey, aR as normalizeEvent, aS as pageTitle, aT as parseHookConfig, aU as parseJson, aV as parseMatcher, aW as parseRegex, aX as parseStdout, aY as parseText, aZ as phonePairs, a_ as pyQuote, a$ as readConnection, b0 as readable, b1 as refusalReason, b2 as render, b3 as resultFromJson, b4 as splitTopLevel, b5 as stripTags, b6 as unescapeHtml, b7 as vendorOf, b8 as withContext, b9 as withDefaults } from '../index-C3UzD0G3.mjs';
@@ -1 +1 @@
1
- export { A as Alias, a as AliasHandler, b as AliasMap, c as AuditFinding, d as AuditRecord, e as AuditReport, B as Bound, C as CONTEXT_KEY, f as CallableTool, g as CommandHandler, h as ConnectorTool, D as Decision, j as DenyHandler, E as EVENTS, k as EVENT_ALIASES, F as FieldKinds, l as FieldSource, m as FinderSource, n as Finding, o as FunctionHandler, H as HANDLER_TYPES, p as Handler, q as HandlerFn, r as HandlerSpec, s as HandlerType, t as HookConfig, u as HookConfigError, v as HookDenied, w as HookError, x as HookEvent, y as HookEventName, z as HookRequest, G as HookResponse, I as HookResult, J as HookRule, K as HookRun, L as HookRunOptions, M as HookedSession, N as HttpHandler, O as HttpTool, P as INBOUND_KINDS, Q as INPUT_TYPES, R as Identifier, S as IdentifierCensus, T as IdentifierSource, U as Identity, V as InboundKind, W as JsonSchema, X as KINDS, Y as LegendEntry, Z as LegendRow, _ as LegendSource, $ as LiveConfig, a0 as LiveTool, a1 as LiveToolError, a2 as LiveTools, a3 as Matcher, a4 as PARSE_MODES, a5 as Pair, a6 as ParseMode, a7 as RecordHandler, a8 as RecordSink, a9 as Recorder, aa as RedactHandler, ab as RedactionAudit, ac as Replay, ad as RequestFn, ae as RunVerdict, af as SeedEntity, ag as SeedRow, ah as SessionLike, ai as TOOL_KINDS, aj as ToolFn, ak as ToolFunctions, al as ToolKind, am as ToolSpec, an as WrappedTools, ao as applyLimit, ap as applyResult, aq as buildTool, ar as canonical, as as definition, at as describeHandler, au as describeMatcher, av as describeTool, aw as emailPairs, ax as emptyConfig, ay as emptyLive, az as eventToJson, aA as explodeIp, aB as findKind, aC as folded, aD as genericPairs, aE as importCallable, aF as inputSchema, aG as interpolateHeaders, aH as interpolatePath, aI as isGlobalIpv4, aJ as jsPattern, aK as jsonPath, aL as loadHookConfig, aM as mapFields, aN as matches, aO as mirrorHandle, aP as namePairs, aQ as newRunKey, aR as normalizeEvent, aS as pageTitle, aT as parseHookConfig, aU as parseJson, aV as parseMatcher, aW as parseRegex, aX as parseStdout, aY as parseText, aZ as phonePairs, a_ as pyQuote, a$ as readConnection, b0 as readable, b1 as refusalReason, b2 as render, b3 as resultFromJson, b4 as splitTopLevel, b5 as stripTags, b6 as unescapeHtml, b7 as vendorOf, b8 as withContext, b9 as withDefaults } from '../index-BaKu5ZSU.js';
1
+ export { A as Alias, a as AliasHandler, b as AliasMap, c as AuditFinding, d as AuditRecord, e as AuditReport, B as Bound, C as CONTEXT_KEY, f as CallableTool, g as CommandHandler, h as ConnectorTool, D as Decision, j as DenyHandler, E as EVENTS, k as EVENT_ALIASES, F as FieldKinds, l as FieldSource, m as FinderSource, n as Finding, o as FunctionHandler, H as HANDLER_TYPES, p as Handler, q as HandlerFn, r as HandlerSpec, s as HandlerType, t as HookConfig, u as HookConfigError, v as HookDenied, w as HookError, x as HookEvent, y as HookEventName, z as HookRequest, G as HookResponse, I as HookResult, J as HookRule, K as HookRun, L as HookRunOptions, M as HookedSession, N as HttpHandler, O as HttpTool, P as INBOUND_KINDS, Q as INPUT_TYPES, R as Identifier, S as IdentifierCensus, T as IdentifierSource, U as Identity, V as InboundKind, W as JsonSchema, X as KINDS, Y as LegendEntry, Z as LegendRow, _ as LegendSource, $ as LiveConfig, a0 as LiveTool, a1 as LiveToolError, a2 as LiveTools, a3 as Matcher, a4 as PARSE_MODES, a5 as Pair, a6 as ParseMode, a7 as RecordHandler, a8 as RecordSink, a9 as Recorder, aa as RedactHandler, ab as RedactionAudit, ac as Replay, ad as RequestFn, ae as RunVerdict, af as SeedEntity, ag as SeedRow, ah as SessionLike, ai as TOOL_KINDS, aj as ToolFn, ak as ToolFunctions, al as ToolKind, am as ToolSpec, an as WrappedTools, ao as applyLimit, ap as applyResult, aq as buildTool, ar as canonical, as as definition, at as describeHandler, au as describeMatcher, av as describeTool, aw as emailPairs, ax as emptyConfig, ay as emptyLive, az as eventToJson, aA as explodeIp, aB as findKind, aC as folded, aD as genericPairs, aE as importCallable, aF as inputSchema, aG as interpolateHeaders, aH as interpolatePath, aI as isGlobalIpv4, aJ as jsPattern, aK as jsonPath, aL as loadHookConfig, aM as mapFields, aN as matches, aO as mirrorHandle, aP as namePairs, aQ as newRunKey, aR as normalizeEvent, aS as pageTitle, aT as parseHookConfig, aU as parseJson, aV as parseMatcher, aW as parseRegex, aX as parseStdout, aY as parseText, aZ as phonePairs, a_ as pyQuote, a$ as readConnection, b0 as readable, b1 as refusalReason, b2 as render, b3 as resultFromJson, b4 as splitTopLevel, b5 as stripTags, b6 as unescapeHtml, b7 as vendorOf, b8 as withContext, b9 as withDefaults } from '../index-C3UzD0G3.js';
@@ -163,8 +163,45 @@ function swapValue(text, needle, replacement) {
163
163
  );
164
164
  }
165
165
 
166
- // src/hooks/alias.ts
166
+ // src/hooks/standInDigits.ts
167
167
  var import_node_crypto = require("crypto");
168
+ function standInDigits(realDigits, identityName) {
169
+ if (!realDigits) return "";
170
+ const digest = (0, import_node_crypto.createHash)("sha256").update(`${identityName}:${realDigits}`).digest("hex");
171
+ let digits = "";
172
+ for (let i = 0; i < realDigits.length; i++)
173
+ digits += String(parseInt(digest[i % digest.length], 16) % 10);
174
+ if (digits !== realDigits) return digits;
175
+ return String((Number(digits[0]) + 1) % 10) + digits.slice(1);
176
+ }
177
+
178
+ // src/hooks/declared.ts
179
+ var DeclaredStandIn = class _DeclaredStandIn {
180
+ alias;
181
+ variants;
182
+ constructor(alias, variants = []) {
183
+ this.alias = typeof alias === "string" && alias.trim() ? alias.trim() : null;
184
+ this.variants = Array.isArray(variants) ? variants.filter(
185
+ (v) => typeof v === "string" && v.trim() !== ""
186
+ ) : [];
187
+ }
188
+ static of(entity) {
189
+ return new _DeclaredStandIn(entity.alias, entity.variants ?? []);
190
+ }
191
+ get declared() {
192
+ return this.alias !== null || this.variants.length > 0;
193
+ }
194
+ /** The pairings for `display`: the real value's forms, then every extra spelling in the
195
+ * same forms, each mapped onto the stand-in. */
196
+ pairs(real, display, build) {
197
+ const out = [...build(real, display)];
198
+ for (const spelling of this.variants) out.push(...build(spelling, display));
199
+ return out;
200
+ }
201
+ };
202
+
203
+ // src/hooks/alias.ts
204
+ var import_node_crypto2 = require("crypto");
168
205
  var GIVEN = [
169
206
  "John",
170
207
  "Mary",
@@ -355,7 +392,7 @@ function findKind(kind, text) {
355
392
  return out;
356
393
  }
357
394
  function newRunKey() {
358
- return (0, import_node_crypto.randomBytes)(32).toString("hex");
395
+ return (0, import_node_crypto2.randomBytes)(32).toString("hex");
359
396
  }
360
397
  function canonical(kind, value) {
361
398
  const text = String(value).normalize("NFKC").trim();
@@ -412,7 +449,7 @@ function explodeIp(text) {
412
449
  return groups.map((g) => g.padStart(4, "0")).join(":") + zone;
413
450
  }
414
451
  function index(runKey, kind, value, salt = "") {
415
- const digest = (0, import_node_crypto.createHmac)("sha256", Buffer.from(runKey, "hex")).update(`${kind}:${value}:${salt}`, "utf8").digest();
452
+ const digest = (0, import_node_crypto2.createHmac)("sha256", Buffer.from(runKey, "hex")).update(`${kind}:${value}:${salt}`, "utf8").digest();
416
453
  return digest.readBigUInt64BE(0);
417
454
  }
418
455
  var pick = (pool, n) => pool[Number(n % BigInt(pool.length))];
@@ -597,6 +634,14 @@ function genericPairs(real, fake) {
597
634
  }
598
635
  return dedupe(out);
599
636
  }
637
+ function pairBuilder(kind) {
638
+ const builders = {
639
+ person_name: namePairs,
640
+ email: emailPairs,
641
+ phone: phonePairs
642
+ };
643
+ return builders[kind] ?? genericPairs;
644
+ }
600
645
  function dedupe(pairs) {
601
646
  const seen = /* @__PURE__ */ new Set();
602
647
  const out = [];
@@ -608,7 +653,12 @@ function dedupe(pairs) {
608
653
  }
609
654
  return out.sort((a, b) => b[0].length - a[0].length);
610
655
  }
656
+ function isSubject(alias) {
657
+ return alias.provenance === "seed";
658
+ }
611
659
  var fullName = (identity) => `${identity.given} ${identity.surname}`;
660
+ var DeclaredOnlyError = class extends Error {
661
+ };
612
662
  var AliasMap = class _AliasMap {
613
663
  constructor(runKey, slugs = [], options = {}) {
614
664
  this.runKey = runKey;
@@ -618,7 +668,14 @@ var AliasMap = class _AliasMap {
618
668
  this.publicLayerWins = options.publicLayerWins ?? true;
619
669
  this.publicMailboxDomains = options.publicMailboxDomains ?? null;
620
670
  this.mintInbound = options.mintInbound ?? [];
671
+ this.declaredOnly = options.declaredOnly ?? false;
672
+ if (this.declaredOnly && this.mintInbound.length)
673
+ throw new DeclaredOnlyError(
674
+ "declared_only and mint_inbound cannot both be set: nothing is minted on sight"
675
+ );
621
676
  }
677
+ runKey;
678
+ slugs;
622
679
  aliases = /* @__PURE__ */ new Map();
623
680
  identities = /* @__PURE__ */ new Map();
624
681
  taken = /* @__PURE__ */ new Set();
@@ -626,6 +683,9 @@ var AliasMap = class _AliasMap {
626
683
  aliasDigests = /* @__PURE__ */ new Set();
627
684
  leaksIn = [];
628
685
  leaksOut = [];
686
+ /** As `leaksIn` / `leaksOut`, for values minted on sight: counted, never a failure. */
687
+ bystandersIn = [];
688
+ bystandersOut = [];
629
689
  unresolvedOut = [];
630
690
  /** Every value minted on sight: `{where, kind, alias}`. */
631
691
  found = [];
@@ -649,6 +709,20 @@ var AliasMap = class _AliasMap {
649
709
  * subject. Off (the default) such a value reaches the agent as it is — the seed
650
710
  * list is the whole map. */
651
711
  mintInbound;
712
+ /** Every private seed must carry its own `alias`; a seed without one is refused instead
713
+ * of getting a generated persona, and nothing is minted on arrival. */
714
+ declaredOnly;
715
+ /** `declaredOnly`: refuse a private value that would need a generated persona. */
716
+ requireDeclared(kind, provenance, declared) {
717
+ if (!this.declaredOnly || declared?.alias) return;
718
+ if (provenance === "seed")
719
+ throw new DeclaredOnlyError(
720
+ `declared_only: the seed of kind '${kind}' carries no \`alias\`; give every private seed its stand-in or turn declared_only off`
721
+ );
722
+ throw new DeclaredOnlyError(
723
+ `declared_only: a value of kind '${kind}' arrived unseeded and nothing may be minted on sight; seed it with an \`alias\`, or turn declared_only off`
724
+ );
725
+ }
652
726
  mailboxDomains() {
653
727
  if (this.publicMailboxDomains === null) return PUBLIC_MAILBOX_DOMAINS;
654
728
  return new Set(this.publicMailboxDomains.map((d) => d.toLowerCase()));
@@ -718,8 +792,14 @@ var AliasMap = class _AliasMap {
718
792
  return alias2;
719
793
  }
720
794
  const identityKey = opts.identityKey ?? `${kind}:${canon}`;
795
+ this.requireDeclared(kind, provenance, opts.declared);
721
796
  const identity = this.identityFor(identityKey);
722
- const [display, variants] = this.derive(kind, real, identity);
797
+ const [display, variants] = this.derive(
798
+ kind,
799
+ real,
800
+ identity,
801
+ opts.declared ?? new DeclaredStandIn()
802
+ );
723
803
  const alias = {
724
804
  kind,
725
805
  canonical: canon,
@@ -842,7 +922,15 @@ var AliasMap = class _AliasMap {
842
922
  }
843
923
  return out;
844
924
  }
845
- derive(kind, real, identity) {
925
+ /** The stand-in and its pairings. A declared stand-in replaces the generated one; the
926
+ * kind's own pair builder runs over it and over every declared spelling. */
927
+ derive(kind, real, identity, declared) {
928
+ const [display, variants] = this.generated(kind, real, identity);
929
+ if (!declared.declared) return [display, variants];
930
+ const chosen = declared.alias ?? display;
931
+ return [chosen, dedupe(declared.pairs(real, chosen, pairBuilder(kind)))];
932
+ }
933
+ generated(kind, real, identity) {
846
934
  if (kind === "person_name") {
847
935
  const display2 = fullName(identity);
848
936
  return [display2, namePairs(real, display2)];
@@ -895,7 +983,7 @@ var AliasMap = class _AliasMap {
895
983
  const existing = this.aliases.get(key2);
896
984
  if (existing) return existing.display;
897
985
  if (this.aliasDigests.has(digest.toLowerCase())) return digest;
898
- const standIn = "sha256:" + (0, import_node_crypto.createHmac)("sha256", Buffer.from(this.runKey, "hex")).update(digest, "utf8").digest("hex");
986
+ const standIn = "sha256:" + (0, import_node_crypto2.createHmac)("sha256", Buffer.from(this.runKey, "hex")).update(digest, "utf8").digest("hex");
899
987
  this.aliasDigests.add(standIn.toLowerCase());
900
988
  const alias = {
901
989
  kind: "digest",
@@ -929,13 +1017,14 @@ var AliasMap = class _AliasMap {
929
1017
  for (const entity of entities) {
930
1018
  const alias = this.mint(entity.type, entity.value, {
931
1019
  identityKey: entity.identity,
932
- role: entity.role ?? "private"
1020
+ role: entity.role ?? "private",
1021
+ declared: DeclaredStandIn.of(entity)
933
1022
  });
934
1023
  if (alias.role === "private") {
935
1024
  for (const slug of this.slugs) {
936
- const standIn = "sha256:" + (0, import_node_crypto.createHash)("sha256").update(`${slug}:${canonical(alias.kind, alias.display)}`, "utf8").digest("hex");
1025
+ const standIn = "sha256:" + (0, import_node_crypto2.createHash)("sha256").update(`${slug}:${canonical(alias.kind, alias.display)}`, "utf8").digest("hex");
937
1026
  alias.variants.push([
938
- "sha256:" + (0, import_node_crypto.createHash)("sha256").update(`${slug}:${alias.canonical}`, "utf8").digest("hex"),
1027
+ "sha256:" + (0, import_node_crypto2.createHash)("sha256").update(`${slug}:${alias.canonical}`, "utf8").digest("hex"),
939
1028
  standIn
940
1029
  ]);
941
1030
  this.aliasDigests.add(standIn.toLowerCase());
@@ -1057,45 +1146,51 @@ var AliasMap = class _AliasMap {
1057
1146
  /** Requirement 3: count what slipped, do not assume nothing did. The scan is
1058
1147
  * case-folded with whitespace collapsed and walks EVERY variant of every alias,
1059
1148
  * not only the pairs the rewriter used. */
1060
- meter(text, where) {
1061
- const haystack = folded(text);
1149
+ /** Every private alias with a real variant of 4+ characters in the folded text,
1150
+ * case subjects first. */
1151
+ surviving(haystack) {
1062
1152
  const pub = this.publicFolded();
1153
+ const found = [];
1063
1154
  for (const alias of this.aliases.values()) {
1064
1155
  if (alias.role === "public") continue;
1065
- for (const [real] of alias.variants) {
1066
- if (real.length >= 4 && !pub.has(folded(real)) && haystack.includes(folded(real))) {
1067
- this.leaksIn.push({
1068
- where,
1069
- kind: alias.kind,
1070
- variant: shorten(real),
1071
- alias: alias.display
1072
- });
1073
- return;
1074
- }
1075
- }
1156
+ const variant = alias.variants.find(
1157
+ ([real]) => real.length >= 4 && !pub.has(folded(real)) && haystack.includes(folded(real))
1158
+ );
1159
+ if (variant !== void 0) found.push([alias, variant[0]]);
1076
1160
  }
1161
+ return [
1162
+ ...found.filter(([a]) => isSubject(a)),
1163
+ ...found.filter(([a]) => !isSubject(a))
1164
+ ];
1165
+ }
1166
+ /** A leak is about a CASE SUBJECT (a seeded entity); a value that only arrived in a
1167
+ * result and was given a stand-in on sight is a bystander, counted apart. */
1168
+ meter(text, where) {
1169
+ const hit = this.surviving(folded(text))[0];
1170
+ if (hit === void 0) return;
1171
+ const [alias, real] = hit;
1172
+ const rows = isSubject(alias) ? this.leaksIn : this.bystandersIn;
1173
+ rows.push({
1174
+ where,
1175
+ kind: alias.kind,
1176
+ variant: shorten(real),
1177
+ alias: alias.display
1178
+ });
1077
1179
  }
1078
- /** Requirement 4: the report and the artifacts must contain no real value. */
1180
+ /** Requirement 4: the report and the artifacts must contain no real value OF A CASE
1181
+ * SUBJECT. Bystanders are counted, never returned. */
1079
1182
  scanOutgoing(text, where) {
1080
- const hits = [];
1081
- const haystack = typeof text === "string" ? folded(text) : "";
1082
- const pub = this.publicFolded();
1083
- for (const alias of this.aliases.values()) {
1084
- if (alias.role === "public") continue;
1085
- for (const [real] of alias.variants) {
1086
- if (real.length >= 4 && !pub.has(folded(real)) && haystack.includes(folded(real))) {
1087
- hits.push({
1088
- check: "leak_outbound",
1089
- where,
1090
- kind: alias.kind,
1091
- alias: alias.display,
1092
- variant: shorten(real)
1093
- });
1094
- break;
1095
- }
1096
- }
1097
- }
1183
+ const found = this.surviving(typeof text === "string" ? folded(text) : "");
1184
+ const row = ([alias, real]) => ({
1185
+ check: "leak_outbound",
1186
+ where,
1187
+ kind: alias.kind,
1188
+ alias: alias.display,
1189
+ variant: shorten(real)
1190
+ });
1191
+ const hits = found.filter(([a]) => isSubject(a)).map(row);
1098
1192
  this.leaksOut.push(...hits);
1193
+ this.bystandersOut.push(...found.filter(([a]) => !isSubject(a)).map(row));
1099
1194
  return hits;
1100
1195
  }
1101
1196
  // ------------------------------------------------------------ reporting
@@ -1192,6 +1287,8 @@ var AliasMap = class _AliasMap {
1192
1287
  leak_through_inbound_detail: this.leaksIn.slice(0, 50),
1193
1288
  leaks_outbound: this.leaksOut.length,
1194
1289
  leaks_outbound_detail: this.leaksOut.slice(0, 50),
1290
+ bystander_leak_through_inbound: this.bystandersIn.length,
1291
+ bystander_leaks_outbound: this.bystandersOut.length,
1195
1292
  unresolved_aliases_outbound: this.unresolvedOut.length,
1196
1293
  unresolved_detail: this.unresolvedOut.slice(0, 50),
1197
1294
  found_inbound: this.found.length,
@@ -1218,8 +1315,9 @@ function mirrorHandle(handle, identity) {
1218
1315
  const surname = identity.surname.toLowerCase();
1219
1316
  const text = handle.toLowerCase();
1220
1317
  const digits = /\d+$/.exec(text);
1221
- const suffix = digits ? digits[0] : "";
1222
- const body = text.slice(0, text.length - suffix.length);
1318
+ const realSuffix = digits ? digits[0] : "";
1319
+ const body = text.slice(0, text.length - realSuffix.length);
1320
+ const suffix = standInDigits(realSuffix, `${given} ${surname}`);
1223
1321
  for (const separator of [".", "_", "-"]) {
1224
1322
  if (body.includes(separator))
1225
1323
  return `${given}${separator}${surname}${suffix}`;
@@ -1467,6 +1565,11 @@ var HookDenied = class extends Error {
1467
1565
  this.handler = handler;
1468
1566
  this.name = "HookDenied";
1469
1567
  }
1568
+ event;
1569
+ toolName;
1570
+ reason;
1571
+ findings;
1572
+ handler;
1470
1573
  };
1471
1574
  var HookError = class extends Error {
1472
1575
  constructor(event, toolName, handler, detail) {
@@ -1477,6 +1580,10 @@ var HookError = class extends Error {
1477
1580
  this.detail = detail;
1478
1581
  this.name = "HookError";
1479
1582
  }
1583
+ event;
1584
+ toolName;
1585
+ handler;
1586
+ detail;
1480
1587
  };
1481
1588
  var isObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
1482
1589
  function resultFromJson(raw, handler = "handler") {
@@ -2021,6 +2128,7 @@ var emptyConfig = () => ({
2021
2128
  aliasPublicLayerWins: true,
2022
2129
  aliasPublicMailboxDomains: null,
2023
2130
  aliasMintInbound: [],
2131
+ aliasDeclaredOnly: false,
2024
2132
  aliasLegend: null,
2025
2133
  vendors: {},
2026
2134
  live: emptyLive()
@@ -2133,7 +2241,8 @@ function parseHookConfig(data, source) {
2133
2241
  "public_layer_wins",
2134
2242
  "public_mailbox_domains",
2135
2243
  "mint_inbound",
2136
- "legend"
2244
+ "legend",
2245
+ "declared_only"
2137
2246
  ].includes(k)
2138
2247
  );
2139
2248
  if (unknownAlias.length)
@@ -2160,6 +2269,13 @@ function parseHookConfig(data, source) {
2160
2269
  throw new HookConfigError(
2161
2270
  `alias.mint_inbound: ${badKinds.join(", ")} cannot be found by a pattern; only ${INBOUND_KINDS.join(", ")} can (a name or a handle is seeded, never guessed)`
2162
2271
  );
2272
+ const declaredOnly = alias.declared_only ?? false;
2273
+ if (typeof declaredOnly !== "boolean")
2274
+ throw new HookConfigError("alias.declared_only must be true or false");
2275
+ if (declaredOnly && mintInboundRaw.length)
2276
+ throw new HookConfigError(
2277
+ "alias.declared_only and alias.mint_inbound cannot both be set: nothing is minted on sight"
2278
+ );
2163
2279
  const legendPath = alias.legend ?? null;
2164
2280
  if (legendPath !== null && (typeof legendPath !== "string" || !legendPath.trim()))
2165
2281
  throw new HookConfigError(
@@ -2192,6 +2308,7 @@ function parseHookConfig(data, source) {
2192
2308
  aliasPublicLayerWins: publicLayerWins,
2193
2309
  aliasPublicMailboxDomains: mailbox,
2194
2310
  aliasMintInbound: mintInboundRaw,
2311
+ aliasDeclaredOnly: declaredOnly,
2195
2312
  aliasLegend: legendPath,
2196
2313
  vendors,
2197
2314
  live: parseLive(data.live ?? {}, data.tools ?? {}),
@@ -2470,6 +2587,8 @@ var CommandHandler = class {
2470
2587
  this.command = command;
2471
2588
  this.opts = opts;
2472
2589
  }
2590
+ command;
2591
+ opts;
2473
2592
  describe() {
2474
2593
  return `command ${this.command}${this.opts.args?.length ? " " + this.opts.args.join(" ") : ""}`;
2475
2594
  }
@@ -2572,6 +2691,8 @@ var HttpHandler = class {
2572
2691
  this.url = url;
2573
2692
  this.opts = opts;
2574
2693
  }
2694
+ url;
2695
+ opts;
2575
2696
  describe() {
2576
2697
  return `http ${this.url}`;
2577
2698
  }
@@ -2608,6 +2729,7 @@ var DenyHandler = class {
2608
2729
  constructor(reason = "denied by rule") {
2609
2730
  this.reason = reason;
2610
2731
  }
2732
+ reason;
2611
2733
  describe() {
2612
2734
  return `deny: ${this.reason}`;
2613
2735
  }
@@ -2620,6 +2742,8 @@ var RecordHandler = class {
2620
2742
  this.sink = sink;
2621
2743
  this.opts = opts;
2622
2744
  }
2745
+ sink;
2746
+ opts;
2623
2747
  describe() {
2624
2748
  return `record -> ${typeof this.sink === "string" ? this.sink : typeof this.sink === "function" ? "callback" : "array"}`;
2625
2749
  }
@@ -2656,6 +2780,7 @@ var RedactHandler = class {
2656
2780
  this.patterns = (opts.patterns ?? []).map((p) => new RegExp(p, "g"));
2657
2781
  this.token = opts.token ?? "[redacted {kind}]";
2658
2782
  }
2783
+ aliases;
2659
2784
  kinds;
2660
2785
  /** Literal strings (a name, a company, a phrase) removed wherever they appear, any
2661
2786
  * case — the arbitrary half of redaction; `patterns` is the shaped half. */
@@ -2716,6 +2841,8 @@ var AliasHandler = class {
2716
2841
  this.aliases = aliases;
2717
2842
  this.opts = opts;
2718
2843
  }
2844
+ aliases;
2845
+ opts;
2719
2846
  describe() {
2720
2847
  if (this.opts.check) return `alias check=${this.opts.check}`;
2721
2848
  return this.opts.direction ? `alias direction=${this.opts.direction}` : "alias";
@@ -2836,6 +2963,8 @@ var FunctionHandler = class {
2836
2963
  this.fn = fn;
2837
2964
  this.name = name;
2838
2965
  }
2966
+ fn;
2967
+ name;
2839
2968
  describe() {
2840
2969
  return `callable ${this.name}`;
2841
2970
  }
@@ -3162,6 +3291,8 @@ var HttpTool = class _HttpTool {
3162
3291
  this.spec = spec;
3163
3292
  this.live = live;
3164
3293
  }
3294
+ spec;
3295
+ live;
3165
3296
  /** Shared across tools: the pace is per tool name, not per HttpTool instance. */
3166
3297
  static pacer = new Pacer();
3167
3298
  /** The status of the most recent answer, for the recording line. */
@@ -3258,6 +3389,8 @@ var CallableTool = class _CallableTool {
3258
3389
  this.spec = spec;
3259
3390
  this.fn = fn;
3260
3391
  }
3392
+ spec;
3393
+ fn;
3261
3394
  static async create(spec, cwd) {
3262
3395
  const fn = await importCallable(spec.options.callable, cwd);
3263
3396
  return new _CallableTool(
@@ -3332,6 +3465,8 @@ var ConnectorTool = class {
3332
3465
  );
3333
3466
  }
3334
3467
  }
3468
+ spec;
3469
+ live;
3335
3470
  connection;
3336
3471
  operation;
3337
3472
  get placeholders() {
@@ -3462,6 +3597,7 @@ var Recorder = class {
3462
3597
  constructor(file) {
3463
3598
  this.file = file;
3464
3599
  }
3600
+ file;
3465
3601
  write(line) {
3466
3602
  fs3.mkdirSync(path2.dirname(this.file), { recursive: true });
3467
3603
  fs3.appendFileSync(this.file, canonical2(line) + "\n");
@@ -3492,6 +3628,7 @@ var Replay = class {
3492
3628
  );
3493
3629
  });
3494
3630
  }
3631
+ file;
3495
3632
  answers = /* @__PURE__ */ new Map();
3496
3633
  tool(spec) {
3497
3634
  const answers = this.answers;
@@ -3532,6 +3669,8 @@ var LiveTools = class _LiveTools {
3532
3669
  if (live.replay) this.replay = new Replay(live.replay);
3533
3670
  if (live.record) this.recorder = new Recorder(live.record);
3534
3671
  }
3672
+ run;
3673
+ live;
3535
3674
  replay;
3536
3675
  recorder;
3537
3676
  built = {};
@@ -3683,6 +3822,9 @@ var Identifier = class {
3683
3822
  this.value = value;
3684
3823
  this.source = source;
3685
3824
  }
3825
+ kind;
3826
+ value;
3827
+ source;
3686
3828
  get key() {
3687
3829
  return folded(this.value);
3688
3830
  }
@@ -3716,6 +3858,7 @@ var FieldSource = class extends IdentifierSource {
3716
3858
  super();
3717
3859
  this.fieldKinds = fieldKinds;
3718
3860
  }
3861
+ fieldKinds;
3719
3862
  name = "fields";
3720
3863
  kindsFor(tool) {
3721
3864
  return { ...this.fieldKinds[ANY_TOOL] ?? {}, ...this.fieldKinds[tool] ?? {} };
@@ -3755,6 +3898,7 @@ var IdentifierCensus = class {
3755
3898
  constructor(sources) {
3756
3899
  this.sources = sources;
3757
3900
  }
3901
+ sources;
3758
3902
  get detectors() {
3759
3903
  return this.sources.map((source) => source.name);
3760
3904
  }
@@ -3793,6 +3937,12 @@ var AuditReport = class {
3793
3937
  this.leakedIdentifiers = leakedIdentifiers;
3794
3938
  this.cleanTexts = cleanTexts;
3795
3939
  }
3940
+ findings;
3941
+ census;
3942
+ detectors;
3943
+ recordsScanned;
3944
+ leakedIdentifiers;
3945
+ cleanTexts;
3796
3946
  get ok() {
3797
3947
  return this.findings.length === 0;
3798
3948
  }
@@ -3836,6 +3986,7 @@ var RedactionAudit = class _RedactionAudit {
3836
3986
  constructor(census) {
3837
3987
  this.census = census;
3838
3988
  }
3989
+ census;
3839
3990
  /** The standard audit: the run's legend, declared field kinds, pattern finders. */
3840
3991
  static forRun(options) {
3841
3992
  return new _RedactionAudit(
@@ -3869,7 +4020,7 @@ var RedactionAudit = class _RedactionAudit {
3869
4020
  };
3870
4021
 
3871
4022
  // src/hooks/run.ts
3872
- var import_node_crypto2 = require("crypto");
4023
+ var import_node_crypto3 = require("crypto");
3873
4024
  var fs4 = __toESM(require("fs"));
3874
4025
  var path3 = __toESM(require("path"));
3875
4026
  var BLOCKING_EVENTS = [
@@ -3913,12 +4064,13 @@ var HookRun = class _HookRun {
3913
4064
  source;
3914
4065
  constructor(config, options) {
3915
4066
  this.config = config;
3916
- this.runId = options.runId ?? `run-${(0, import_node_crypto2.randomBytes)(6).toString("hex")}`;
4067
+ this.runId = options.runId ?? `run-${(0, import_node_crypto3.randomBytes)(6).toString("hex")}`;
3917
4068
  this.runKey = options.runKey ?? newRunKey();
3918
4069
  this.alias = new AliasMap(this.runKey, options.slugs ?? config.aliasSlugs, {
3919
4070
  publicLayerWins: config.aliasPublicLayerWins,
3920
4071
  publicMailboxDomains: config.aliasPublicMailboxDomains,
3921
- mintInbound: options.mintInbound ?? config.aliasMintInbound
4072
+ mintInbound: options.mintInbound ?? config.aliasMintInbound,
4073
+ declaredOnly: options.declaredOnly ?? config.aliasDeclaredOnly
3922
4074
  });
3923
4075
  this.cwd = options.cwd ?? process.cwd();
3924
4076
  this.runDir = options.runDir ?? path3.join(this.cwd, "runs", this.runId);
@@ -4396,6 +4548,10 @@ var HookedSession = class {
4396
4548
  this.vendor = vendor;
4397
4549
  this.requestFn = requestFn;
4398
4550
  }
4551
+ run;
4552
+ inner;
4553
+ vendor;
4554
+ requestFn;
4399
4555
  async call(tool, args = {}, ...rest) {
4400
4556
  const [real, context] = await this.run.beforeCall(
4401
4557
  tool,