@antprofuse/saddle-islands-tools 0.0.0-stage → 0.1.4

package/tools/modules/backend/metadata.mjs

@@ -0,0 +1,66 @@
+import assert from 'node:assert/strict';
+import {spawnSync} from 'node:child_process';
+import {fileURLToPath} from 'node:url';
+export const contextKeys=['trace-info-bin','ldc-info-bin','request-info-bin','profuse-context-bin'];
+const receiver=fileURLToPath(new URL('./context-receiver.py',import.meta.url));
+// Read every native value, including duplicates. Never synthesize absent groups.
+export function observeMetadata(metadata,deadline){
+ const raw=[];
+ for(const key of contextKeys)for(const value of metadata.get(key)){
+  assert(Buffer.isBuffer(value),`${key}: native binary required`);
+  raw.push([key,value.toString('hex')]);
+ }
+ const decoded=spawnSync('python3',['-B',receiver],{input:JSON.stringify(raw),encoding:'utf8'});
+ if(decoded.status!==0){const error=new Error(`invalid grouped metadata: ${decoded.stderr||decoded.error||''}`);error.contextRaw=raw;throw error;}
+ const groups=JSON.parse(decoded.stdout);
+ return {raw,groups,grpcDeadline:deadline instanceof Date?deadline.getTime():deadline};
+}
+export function assertMetadata(records,expectations){
+ // Ownership comes from the expected protobuf plan, never from wire metadata.
+ assert(Array.isArray(expectations),'independent expected call ownership required');
+ const plans=new Map(),owners=new Map();
+ for(const owner of expectations){
+  assert(!owners.has(owner.ownerId),'duplicate expected owner');owners.set(owner.ownerId,owner);
+  for(const plan of owner.plans){assert(!plans.has(plan.planId),'duplicate expected plan');plans.set(plan.planId,{...plan,owner});}
+ }
+ const used=new Set(),checked=[];
+ for(const record of records){
+  const plan=plans.get(record.planId);assert(plan,'unassigned gRPC record');
+  assert.equal(record.ownerId,plan.owner.ownerId,'record ownership differs from plan');
+  assert(!used.has(record.planId),'extra record for expected call');used.add(record.planId);
+  assert.equal(record.method,plan.method,'planned gRPC method');
+ }
+ for(const [id,plan]of plans)assert(used.has(id)||plan.optional,'missing planned metadata call');
+ for(const owner of owners.values()){
+  const own=records.filter(record=>plans.get(record.planId).owner===owner);
+  if(!own.length)continue;
+  assert(owner.ingress,'ingress must be registered before the RPC');
+  checked.push(...checkOwner(own,owner.ingress));
+ }
+ assert.equal(checked.length,records.length,'all actual records must be checked');
+ return checked;
+}
+function checkOwner(own,ingress){
+ const sequences=[];
+ for(const record of own){
+  assert(record.context,'missing observed context');
+  const {groups,grpcDeadline}=record.context;
+  const trace=groups['trace-info-bin'],req=groups['request-info-bin'];
+  assert(trace.rpcId.startsWith(ingress.traceInfo.rpcId+'.'),'child rpc identity');
+  const suffix=trace.rpcId.slice(ingress.traceInfo.rpcId.length+1);
+  assert(/^[1-9][0-9]*$/.test(suffix),'positive child sequence');
+  sequences.push(Number(suffix));
+  assert.deepEqual(trace,{...ingress.traceInfo,rpcId:ingress.traceInfo.rpcId+'.'+suffix});
+  assert.deepEqual(groups['ldc-info-bin'],ingress.ldcInfo,'LDC including unknown extensions');
+  assert.deepEqual(req,{requestId:ingress.requestId,callId:ingress.callId+'-'+suffix,deadlineUnixMs:req.deadlineUnixMs});
+  assert(Number.isSafeInteger(req.deadlineUnixMs)&&req.deadlineUnixMs>ingress.startedAt,'valid active absolute deadline');
+  assert(req.deadlineUnixMs<=ingress.deadline,'deadline extended');
+  // Native gRPC timeout is relative at receipt; allow transit and millisecond rounding.
+  assert(Number.isFinite(grpcDeadline)&&Math.abs(grpcDeadline-req.deadlineUnixMs)<100,'grpc timeout differs from shared deadline');
+  assert.equal(Object.hasOwn(groups,'profuse-context-bin'),Object.hasOwn(ingress,'profuseContext'),'missing versus empty profuseContext');
+  if(Object.hasOwn(ingress,'profuseContext'))assert.deepEqual(groups['profuse-context-bin'],ingress.profuseContext);
+ }
+ assert.equal(new Set(sequences).size,sequences.length,'reused child identity');
+ assert.deepEqual([...sequences].sort((a,b)=>a-b),Array.from({length:sequences.length},(_,i)=>i+1));
+ return own;
+}

package/tools/modules/backend/package-lock.json

@@ -0,0 +1,362 @@
+{
+  "name": "saddle-backend-test-tools",
+  "version": "0.1.4",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "saddle-backend-test-tools",
+      "version": "0.1.4",
+      "dependencies": {
+        "@grpc/grpc-js": "1.14.4",
+        "@grpc/proto-loader": "0.8.0",
+        "protobufjs": "7.5.4",
+        "yaml": "2.8.1"
+      }
+    },
+    "node_modules/@grpc/grpc-js": {
+      "version": "1.14.4",
+      "resolved": "https://registry.npmmirror.com/@grpc/grpc-js/-/grpc-js-1.14.4.tgz",
+      "integrity": "sha512-k9Dj3DV/itK9D06Y8f190Qgop7/Ui+D0njFV3LHMPwPT75DpXLQohE9Wmz0QElrJnzsjB7KPWiKJbOl7IPDArQ==",
+      "license": "Apache-2.0",
+      "dependencies": {
+        "@grpc/proto-loader": "^0.8.0",
+        "@js-sdsl/ordered-map": "^4.4.2"
+      },
+      "engines": {
+        "node": ">=12.10.0"
+      }
+    },
+    "node_modules/@grpc/proto-loader": {
+      "version": "0.8.0",
+      "resolved": "https://registry.npmmirror.com/@grpc/proto-loader/-/proto-loader-0.8.0.tgz",
+      "integrity": "sha512-rc1hOQtjIWGxcxpb9aHAfLpIctjEnsDehj0DAiVfBlmT84uvR0uUtN2hEi/ecvWVjXUGf5qPF4qEgiLOx1YIMQ==",
+      "license": "Apache-2.0",
+      "dependencies": {
+        "lodash.camelcase": "^4.3.0",
+        "long": "^5.0.0",
+        "protobufjs": "^7.5.3",
+        "yargs": "^17.7.2"
+      },
+      "bin": {
+        "proto-loader-gen-types": "build/bin/proto-loader-gen-types.js"
+      },
+      "engines": {
+        "node": ">=6"
+      }
+    },
+    "node_modules/@js-sdsl/ordered-map": {
+      "version": "4.4.2",
+      "resolved": "https://registry.npmmirror.com/@js-sdsl/ordered-map/-/ordered-map-4.4.2.tgz",
+      "integrity": "sha512-iUKgm52T8HOE/makSxjqoWhe95ZJA1/G1sYsGev2JDKUSS14KAgg1LHb+Ba+IPow0xflbnSkOsZcO08C7w1gYw==",
+      "license": "MIT",
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/js-sdsl"
+      }
+    },
+    "node_modules/@protobufjs/aspromise": {
+      "version": "1.1.2",
+      "resolved": "https://registry.npmmirror.com/@protobufjs/aspromise/-/aspromise-1.1.2.tgz",
+      "integrity": "sha512-j+gKExEuLmKwvz3OgROXtrJ2UG2x8Ch2YZUxahh+s1F2HZ+wAceUNLkvy6zKCPVRkU++ZWQrdxsUeQXmcg4uoQ==",
+      "license": "BSD-3-Clause"
+    },
+    "node_modules/@protobufjs/base64": {
+      "version": "1.1.2",
+      "resolved": "https://registry.npmmirror.com/@protobufjs/base64/-/base64-1.1.2.tgz",
+      "integrity": "sha512-AZkcAA5vnN/v4PDqKyMR5lx7hZttPDgClv83E//FMNhR2TMcLUhfRUBHCmSl0oi9zMgDDqRUJkSxO3wm85+XLg==",
+      "license": "BSD-3-Clause"
+    },
+    "node_modules/@protobufjs/codegen": {
+      "version": "2.0.5",
+      "resolved": "https://registry.npmmirror.com/@protobufjs/codegen/-/codegen-2.0.5.tgz",
+      "integrity": "sha512-zgXFLzW3Ap33e6d0Wlj4MGIm6Ce8O89n/apUaGNB/jx+hw+ruWEp7EwGUshdLKVRCxZW12fp9r40E1mQrf/34g==",
+      "license": "BSD-3-Clause"
+    },
+    "node_modules/@protobufjs/eventemitter": {
+      "version": "1.1.1",
+      "resolved": "https://registry.npmmirror.com/@protobufjs/eventemitter/-/eventemitter-1.1.1.tgz",
+      "integrity": "sha512-vW1GmwMZNnL+gMRaovlh9yZX74kc+TTU3FObkkurpMaRtBfLP3ldjS9KQWlwZgraRE0+dheEEoAxdzcJQ8eXZg==",
+      "license": "BSD-3-Clause"
+    },
+    "node_modules/@protobufjs/fetch": {
+      "version": "1.1.1",
+      "resolved": "https://registry.npmmirror.com/@protobufjs/fetch/-/fetch-1.1.1.tgz",
+      "integrity": "sha512-GpptLrs57adMSuHi3VNj0mAF8dwh36LMaYF6XyJ6JMWlVsc+t42tm1HSEDmOs3A8fC9yyeisgLhsTVQokOZ0zw==",
+      "license": "BSD-3-Clause",
+      "dependencies": {
+        "@protobufjs/aspromise": "^1.1.1"
+      }
+    },
+    "node_modules/@protobufjs/float": {
+      "version": "1.0.2",
+      "resolved": "https://registry.npmmirror.com/@protobufjs/float/-/float-1.0.2.tgz",
+      "integrity": "sha512-Ddb+kVXlXst9d+R9PfTIxh1EdNkgoRe5tOX6t01f1lYWOvJnSPDBlG241QLzcyPdoNTsblLUdujGSE4RzrTZGQ==",
+      "license": "BSD-3-Clause"
+    },
+    "node_modules/@protobufjs/inquire": {
+      "version": "1.1.2",
+      "resolved": "https://registry.npmmirror.com/@protobufjs/inquire/-/inquire-1.1.2.tgz",
+      "integrity": "sha512-pa0vFRuws4wkvaXKK1uXZMAwAX4/t8ANaJo45iw/oQHNQ9q5xUzwgFmVJGXiga2BeN+zpX7Vf9vmsiIa2J+MUw==",
+      "license": "BSD-3-Clause"
+    },
+    "node_modules/@protobufjs/path": {
+      "version": "1.1.2",
+      "resolved": "https://registry.npmmirror.com/@protobufjs/path/-/path-1.1.2.tgz",
+      "integrity": "sha512-6JOcJ5Tm08dOHAbdR3GrvP+yUUfkjG5ePsHYczMFLq3ZmMkAD98cDgcT2iA1lJ9NVwFd4tH/iSSoe44YWkltEA==",
+      "license": "BSD-3-Clause"
+    },
+    "node_modules/@protobufjs/pool": {
+      "version": "1.1.0",
+      "resolved": "https://registry.npmmirror.com/@protobufjs/pool/-/pool-1.1.0.tgz",
+      "integrity": "sha512-0kELaGSIDBKvcgS4zkjz1PeddatrjYcmMWOlAuAPwAeccUrPHdUqo/J6LiymHHEiJT5NrF1UVwxY14f+fy4WQw==",
+      "license": "BSD-3-Clause"
+    },
+    "node_modules/@protobufjs/utf8": {
+      "version": "1.1.2",
+      "resolved": "https://registry.npmmirror.com/@protobufjs/utf8/-/utf8-1.1.2.tgz",
+      "integrity": "sha512-b1UQwcEZ4yCnMCD8DAL1VlbvBJE9/IX4FTIp7BG1xYpf29SLazLSrqUkj4w7Y5y7cCVP6E5tcqqcI0xemPkHug==",
+      "license": "BSD-3-Clause"
+    },
+    "node_modules/@types/node": {
+      "version": "26.6.5",
+      "resolved": "https://registry.npmmirror.com/@types/node/-/node-26.6.5.tgz",
+      "integrity": "sha512-uMzsv9stDdofIZBx4UGh4Z9ZgXnGC9seRDscilBcTHAeOFk67MZg/k9bWVfO+bk4qZmG+l52hRnLwUiH2LnJTg==",
+      "license": "MIT",
+      "dependencies": {
+        "undici-types": "~8.9.0"
+      }
+    },
+    "node_modules/ansi-regex": {
+      "version": "5.0.1",
+      "resolved": "https://registry.npmmirror.com/ansi-regex/-/ansi-regex-5.0.1.tgz",
+      "integrity": "sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/ansi-styles": {
+      "version": "4.3.0",
+      "resolved": "https://registry.npmmirror.com/ansi-styles/-/ansi-styles-4.3.0.tgz",
+      "integrity": "sha512-zbB9rCJAT1rbjiVDb2hqKFHNYLxgtk8NURxZ3IZwD3F6NtxbXZQCnnSi1Lkx+IDohdPlFp222wVALIheZJQSEg==",
+      "license": "MIT",
+      "dependencies": {
+        "color-convert": "^2.0.1"
+      },
+      "engines": {
+        "node": ">=8"
+      },
+      "funding": {
+        "url": "https://github.com/chalk/ansi-styles?sponsor=1"
+      }
+    },
+    "node_modules/cliui": {
+      "version": "8.0.1",
+      "resolved": "https://registry.npmmirror.com/cliui/-/cliui-8.0.1.tgz",
+      "integrity": "sha512-BSeNnyus75C4//NQ9gQt1/csTXyo/8Sb+afLAkzAptFuMsod9HFokGNudZpi/oQV73hnVK+sR+5PVRMd+Dr7YQ==",
+      "license": "ISC",
+      "dependencies": {
+        "string-width": "^4.2.0",
+        "strip-ansi": "^6.0.1",
+        "wrap-ansi": "^7.0.0"
+      },
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/color-convert": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmmirror.com/color-convert/-/color-convert-2.0.1.tgz",
+      "integrity": "sha512-RRECPsj7iu/xb5oKYcsFHSppFNnsj/52OVTRKb4zP5onXwVF3zVmmToNcOfGC+CRDpfK/U584fMg38ZHCaElKQ==",
+      "license": "MIT",
+      "dependencies": {
+        "color-name": "~1.1.4"
+      },
+      "engines": {
+        "node": ">=7.0.0"
+      }
+    },
+    "node_modules/color-name": {
+      "version": "1.1.4",
+      "resolved": "https://registry.npmmirror.com/color-name/-/color-name-1.1.4.tgz",
+      "integrity": "sha512-dOy+3AuW3a2wNbZHIuMZpTcgjGuLU/uBL/ubcZF9OXbDo8ff4O8yVp5Bf0efS8uEoYo5q4Fx7dY9OgQGXgAsQA==",
+      "license": "MIT"
+    },
+    "node_modules/emoji-regex": {
+      "version": "8.0.0",
+      "resolved": "https://registry.npmmirror.com/emoji-regex/-/emoji-regex-8.0.0.tgz",
+      "integrity": "sha512-MSjYzcWNOA0ewAHpz0MxpYFvwg6yjy1NG3xteoqz644VCo/RPgnr1/GGt+ic3iJTzQ8Eu3TdM14SawnVUmGE6A==",
+      "license": "MIT"
+    },
+    "node_modules/escalade": {
+      "version": "3.2.0",
+      "resolved": "https://registry.npmmirror.com/escalade/-/escalade-3.2.0.tgz",
+      "integrity": "sha512-WUj2qlxaQtO4g6Pq5c29GTcWGDyd8itL8zTlipgECz3JesAiiOKotd8JU6otB3PACgG6xkJUyVhboMS+bje/jA==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=6"
+      }
+    },
+    "node_modules/get-caller-file": {
+      "version": "2.0.5",
+      "resolved": "https://registry.npmmirror.com/get-caller-file/-/get-caller-file-2.0.5.tgz",
+      "integrity": "sha512-DyFP3BM/3YHTQOCUL/w0OZHR0lpKeGrxotcHWcqNEdnltqFwXVfhEBQ94eIo34AfQpo0rGki4cyIiftY06h2Fg==",
+      "license": "ISC",
+      "engines": {
+        "node": "6.* || 8.* || >= 10.*"
+      }
+    },
+    "node_modules/is-fullwidth-code-point": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmmirror.com/is-fullwidth-code-point/-/is-fullwidth-code-point-3.0.0.tgz",
+      "integrity": "sha512-zymm5+u+sCsSWyD9qNaejV3DFvhCKclKdizYaJUuHA83RLjb7nSuGnddCHGv0hk+KY7BMAlsWeK4Ueg6EV6XQg==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/lodash.camelcase": {
+      "version": "4.3.0",
+      "resolved": "https://registry.npmmirror.com/lodash.camelcase/-/lodash.camelcase-4.3.0.tgz",
+      "integrity": "sha512-TwuEnCnxbc3rAvhf/LbG7tJUDzhqXyFnv3dtzLOPgCG/hODL7WFnsbwktkD7yUV0RrreP/l1PALq/YSg6VvjlA==",
+      "license": "MIT"
+    },
+    "node_modules/long": {
+      "version": "5.3.2",
+      "resolved": "https://registry.npmmirror.com/long/-/long-5.3.2.tgz",
+      "integrity": "sha512-mNAgZ1GmyNhD7AuqnTG3/VQ26o760+ZYBPKjPvugO8+nLbYfX6TVpJPseBvopbdY+qpZ/lKUnmEc1LeZYS3QAA==",
+      "license": "Apache-2.0"
+    },
+    "node_modules/protobufjs": {
+      "version": "7.5.4",
+      "resolved": "https://registry.npmmirror.com/protobufjs/-/protobufjs-7.5.4.tgz",
+      "integrity": "sha512-CvexbZtbov6jW2eXAvLukXjXUW1TzFaivC46BpWc/3BpcCysb5Vffu+B3XHMm8lVEuy2Mm4XGex8hBSg1yapPg==",
+      "hasInstallScript": true,
+      "license": "BSD-3-Clause",
+      "dependencies": {
+        "@protobufjs/aspromise": "^1.1.2",
+        "@protobufjs/base64": "^1.1.2",
+        "@protobufjs/codegen": "^2.0.4",
+        "@protobufjs/eventemitter": "^1.1.0",
+        "@protobufjs/fetch": "^1.1.0",
+        "@protobufjs/float": "^1.0.2",
+        "@protobufjs/inquire": "^1.1.0",
+        "@protobufjs/path": "^1.1.2",
+        "@protobufjs/pool": "^1.1.0",
+        "@protobufjs/utf8": "^1.1.0",
+        "@types/node": ">=13.7.0",
+        "long": "^5.0.0"
+      },
+      "engines": {
+        "node": ">=12.0.0"
+      }
+    },
+    "node_modules/require-directory": {
+      "version": "2.1.1",
+      "resolved": "https://registry.npmmirror.com/require-directory/-/require-directory-2.1.1.tgz",
+      "integrity": "sha512-fGxEI7+wsG9xrvdjsrlmL22OMTTiHRwAMroiEeMgq8gzoLC/PQr7RsRDSTLUg/bZAZtF+TVIkHc6/4RIKrui+Q==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
+    "node_modules/string-width": {
+      "version": "4.2.3",
+      "resolved": "https://registry.npmmirror.com/string-width/-/string-width-4.2.3.tgz",
+      "integrity": "sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g==",
+      "license": "MIT",
+      "dependencies": {
+        "emoji-regex": "^8.0.0",
+        "is-fullwidth-code-point": "^3.0.0",
+        "strip-ansi": "^6.0.1"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/strip-ansi": {
+      "version": "6.0.1",
+      "resolved": "https://registry.npmmirror.com/strip-ansi/-/strip-ansi-6.0.1.tgz",
+      "integrity": "sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A==",
+      "license": "MIT",
+      "dependencies": {
+        "ansi-regex": "^5.0.1"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/undici-types": {
+      "version": "8.9.0",
+      "resolved": "https://registry.npmmirror.com/undici-types/-/undici-types-8.9.0.tgz",
+      "integrity": "sha512-KTDyRTYX8sWmKXAikPHHSyc63CRPETMctyjKFupcC6OBLXT3xsN0e9aF7m+mIXutFWpUXuedtowG7iLOzp0kQg==",
+      "license": "MIT"
+    },
+    "node_modules/wrap-ansi": {
+      "version": "7.0.0",
+      "resolved": "https://registry.npmmirror.com/wrap-ansi/-/wrap-ansi-7.0.0.tgz",
+      "integrity": "sha512-YVGIj2kamLSTxw6NsZjoBxfSwsn0ycdesmc4p+Q21c5zPuZ1pl+NfxVdxPtdHvmNVOQ6XSYG4AUtyt/Fi7D16Q==",
+      "license": "MIT",
+      "dependencies": {
+        "ansi-styles": "^4.0.0",
+        "string-width": "^4.1.0",
+        "strip-ansi": "^6.0.0"
+      },
+      "engines": {
+        "node": ">=10"
+      },
+      "funding": {
+        "url": "https://github.com/chalk/wrap-ansi?sponsor=1"
+      }
+    },
+    "node_modules/y18n": {
+      "version": "5.0.8",
+      "resolved": "https://registry.npmmirror.com/y18n/-/y18n-5.0.8.tgz",
+      "integrity": "sha512-0pfFzegeDWJHJIAmTLRP2DwHjdF5s7jo9tuztdQxAhINCdvS+3nGINqPd00AphqJR/0LhANUS6/+7SCb98YOfA==",
+      "license": "ISC",
+      "engines": {
+        "node": ">=10"
+      }
+    },
+    "node_modules/yaml": {
+      "version": "2.8.1",
+      "resolved": "https://registry.npmmirror.com/yaml/-/yaml-2.8.1.tgz",
+      "integrity": "sha512-lcYcMxX2PO9XMGvAJkJ3OsNMw+/7FKes7/hgerGUYWIoWu5j/+YQqcZr5JnPZWzOsEBgMbSbiSTn/dv/69Mkpw==",
+      "license": "ISC",
+      "bin": {
+        "yaml": "bin.mjs"
+      },
+      "engines": {
+        "node": ">= 14.6"
+      }
+    },
+    "node_modules/yargs": {
+      "version": "17.7.3",
+      "resolved": "https://registry.npmmirror.com/yargs/-/yargs-17.7.3.tgz",
+      "integrity": "sha512-GZtjxm/J/4TSxuL3FNYjCmLktBTnIw/rVmKSIyKeYAZpmJB2ig9VauCC5xsa82GNKVKDAqpOn3KVzNt0zmrU0g==",
+      "license": "MIT",
+      "dependencies": {
+        "cliui": "^8.0.1",
+        "escalade": "^3.1.1",
+        "get-caller-file": "^2.0.5",
+        "require-directory": "^2.1.1",
+        "string-width": "^4.2.3",
+        "y18n": "^5.0.5",
+        "yargs-parser": "^21.1.1"
+      },
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/yargs-parser": {
+      "version": "21.1.1",
+      "resolved": "https://registry.npmmirror.com/yargs-parser/-/yargs-parser-21.1.1.tgz",
+      "integrity": "sha512-tVpsJW7DdjecAiFpbIB1e3qxIQsE6NoPc5/eTdrbbIC4h0LVsWhnoa3g+m2HclBIujHzsxZ4VJVA+GUuc2/LBw==",
+      "license": "ISC",
+      "engines": {
+        "node": ">=12"
+      }
+    }
+  }
+}

package/tools/modules/backend/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "saddle-backend-test-tools",
+  "version": "0.1.4",
+  "private": true,
+  "type": "module",
+  "dependencies": {
+    "@grpc/grpc-js": "1.14.4",
+    "@grpc/proto-loader": "0.8.0",
+    "protobufjs": "7.5.4",
+    "yaml": "2.8.1"
+  },
+  "scripts": {
+    "selftest": "node --test *.test.mjs"
+  }
+}

package/tools/modules/backend/paths.mjs

@@ -0,0 +1,11 @@
+import assert from 'node:assert/strict';
+import {realpath,access} from 'node:fs/promises';
+import {resolve,relative,isAbsolute} from 'node:path';
+export async function within(root,file,label='dependency'){
+ const base=await realpath(resolve(root)),target=await realpath(resolve(file)),rel=relative(base,target);
+ assert(rel!== '..'&&!rel.startsWith('../')&&!isAbsolute(rel),`${label} escapes declared root`);return target;
+}
+export async function preflight({projectRoot,repositoryRoot,adapter,proto,binary,list=false}){
+ await within(repositoryRoot,projectRoot,'project');await within(projectRoot,adapter,'adapter');await within(repositoryRoot,proto,'protocol');
+ if(!list)await access(resolve(binary));
+}

package/tools/modules/backend/product.mjs

@@ -0,0 +1,48 @@
+import {writeFile,mkdir,cp} from 'node:fs/promises';
+import {resolve} from 'node:path';
+import {randomUUID} from 'node:crypto';
+import assert from 'node:assert/strict';
+import {port,processStart,until} from './util.mjs';
+export async function product({binary,app,alias,db,mock,out,business='',encodeRequest=(_request,body)=>JSON.stringify(body),databaseConcurrency=4,rpcConcurrency=4,timeout=5000}) {
+  assert(binary,'missing real product executable --binary');assert(app,'--app must be explicit deployment_app');assert(/^[A-Za-z0-9_]+$/.test(alias),'invalid grpc deployment alias');
+  await mkdir(out,{recursive:true});if(db)await cp(db.mappings,resolve(out,'mappings'),{recursive:true});const http=await port(),management=await port();
+  const config=`[framework]
+listen = "127.0.0.1:${http}"
+[framework.management]
+bind = "127.0.0.1:${management}"
+[framework.lifecycle]
+startTimeoutMs = 30000
+shutdownTimeoutMs = 10000
+[framework.admission]
+cpuCores = 2
+memoryMb = 256
+requestTimeoutMs = ${timeout}
+[framework.admission.dependencies]
+databaseConcurrency = ${databaseConcurrency}
+profusecontractConcurrency = ${rpcConcurrency}
+[framework.grpc.${alias}]
+authority = "http://127.0.0.1:${mock.port}"
+[framework.observability.logging]
+directory = "${resolve(out,'logs')}"
+rotation = "daily"
+${db?`[secrets]
+databaseUrlEnv = "BT_PRIVATE_DATABASE_URL"
+[database]
+mappingDir = "mappings"
+`:'[secrets]\n'}${business}`;
+
+  const configPath=resolve(out,'saddle.toml');await writeFile(configPath,config);
+  const proc=await processStart(resolve(binary),['--config',configPath],out,{...(db?{BT_PRIVATE_DATABASE_URL:db.url}:{}),SADDLE_BOOTSTRAP_LOG_DIRECTORY:resolve(out,'bootstrap')});
+  try{await until(async()=>{assert.equal(proc.child.exitCode,null,'product exited during startup');const r=await fetch(`http://127.0.0.1:${management}/ready`);assert.equal(r.status,200);assert.deepEqual(await r.json(),{ready:true});},30000);}catch(e){await proc.stop();throw e;}
+  return {proc,http,management,async call(operation,request,user='synthetic-user-A',options={}){
+    const id=randomUUID(),callId=randomUUID(),startedAt=Date.now(),deadline=options.deadline??startedAt+timeout;const body={target:{app:options.app??app,interfaceId:operation},profuseGwContext:{userInfo:{userId:user},traceInfo:{traceId:id,rpcId:'0'},ldcInfo:{zone:'test',idc:'local',env:'test'}},requestData:request};
+    if(options.traceInfo)body.profuseGwContext.traceInfo=options.traceInfo;
+    if(options.ldcInfo)body.profuseGwContext.ldcInfo=options.ldcInfo;
+    if(Object.hasOwn(options,'profuseContext'))body.profuseContext=options.profuseContext;
+    const ingress={requestId:id,callId,startedAt,deadline,traceInfo:body.profuseGwContext.traceInfo,ldcInfo:body.profuseGwContext.ldcInfo,...(Object.hasOwn(body,'profuseContext')?{profuseContext:body.profuseContext}:{})};
+    mock.registerIngress(ingress);
+    const requestRaw=options.rawBody??encodeRequest(request,body,options);
+    const r=await fetch(`http://127.0.0.1:${http}/saddle/v1/ingress/profusegw/invoke`,{method:'POST',headers:{'Content-Type':'application/json','X-Request-Id':id,'X-Call-Id':callId,'X-Deadline-Unix-Ms':String(deadline)},body:requestRaw,signal:AbortSignal.any([AbortSignal.timeout(timeout+5000),...(options.signal?[options.signal]:[])])});
+    const raw=await r.text();let response=null;try{if(raw)response=JSON.parse(raw);}catch(e){throw Error(`invalid JSON HTTP response status ${r.status}: ${e.message}`);}return {status:r.status,body:response,raw,request:body,requestRaw,ingress,completedAt:Date.now()};
+  },async close(){await proc.stop();assert.equal((await proc.done).code,0,'product did not finish a clean shutdown');}};
+}

package/tools/modules/backend/rejection-logs.mjs

@@ -0,0 +1,33 @@
+import assert from 'node:assert/strict';
+const value=(c,k)=>c?.[k]?.state==='present'?c[k].value:undefined;
+const identity=e=>e.request_identity??e.context?.requestInfo?.requestId??value(e.context,'request');
+export function assertDecodeRejection(logs,actual,{operation,emergency=[],calls=[]}={}){
+ assert.equal(actual.status,400,'decode rejection HTTP400');assert.equal(calls.length,0,'decode rejection made RPC');
+ const i=actual.ingress,owned=logs.filter(e=>identity(e)===i.requestId);
+ const stages=owned.filter(e=>e.recordSchema==='1.0'&&e.context?.schemaVersion==='1.0');
+ assert(stages.length,'missing schema1 request context');
+ const locals=new Set(),tasks=new Set();
+ for(const e of stages){const c=e.context;assert.equal(c.requestInfo.callId,i.callId,'request call ownership');assert.equal(c.traceInfo.traceId,i.traceInfo.traceId);assert.equal(c.traceInfo.rpcId,i.traceInfo.rpcId);assert.equal(c.interfaceInfo.interfaceId,operation);assert.equal(c.executionInfo.phase,'reading','decode rejection entered execution');assert.equal(c._meta.fieldStates['/executionInfo/dbOperation'],'not_applicable');assert.equal(c._meta.fieldStates['/executionInfo/scopeId'],'not_established');locals.add(c.requestInfo.localRequestId);tasks.add(c.executionInfo.taskId);}
+ assert.equal(locals.size,1);assert.equal(tasks.size,1);
+ const records=emergency.filter(e=>identity(e)===i.requestId);
+ const bound=records.filter(e=>e.event==='request_account_bound'&&e.schema==='request-account-identity/1');assert.equal(bound.length,1,'missing/duplicate account binding');
+ const b=bound[0];assert(Number.isInteger(b.ledger_instance)&&b.ledger_instance>0,'missing ledger instance');const span=value(b.context,'span_id');assert(span,'missing owned span');
+ const check=e=>{const c=e.context;assert.equal(c.schema_version,2,'account context schema');assert.equal(String(c.local_request),[...locals][0],'local request ownership');assert.equal(value(c,'request'),i.requestId);assert.equal(value(c,'trace_id'),i.traceInfo.traceId);assert.equal(value(c,'rpc_id'),i.traceInfo.rpcId);assert.equal(value(c,'span_id'),span,'span ownership');assert.equal(value(c,'operation'),operation);assert.equal(String(value(c,'task')),[...tasks][0]);assert.equal(value(c,'lifecycle'),'reading');assert.equal(c.db_operation.state,'not_applicable');assert.equal(c.scope.state,'not_established');};
+ for(const e of records)check(e);
+ const related=logs.filter(e=>identity(e)===i.requestId||(e.trace_id===i.traceInfo.traceId&&e.span_id===span));
+ for(const e of related){if(identity(e)!==undefined)assert.equal(identity(e),i.requestId,'cross-request span');if(e.trace_id!==undefined)assert.equal(e.trace_id,i.traceInfo.traceId);if(e.rpc_id!==undefined)assert.equal(e.rpc_id,i.traceInfo.rpcId);assert(!['handler','database','profuse_contract','grpc'].includes(e.call_kind)&&!['handler','database','profuse_contract'].includes(e.stage),'decode rejection entered handler/DB/RPC');}
+ const root=related.filter(e=>e.call_kind==='external_request');
+ for(const event of ['framework.call.started','framework.call.finished'])assert.equal(root.filter(e=>e.event===event).length,1,'missing/duplicate root '+event);
+ for(const e of root)assert.equal(e.operation,operation);
+ const finish=root.find(e=>e.event==='framework.call.finished');assert.equal(finish.error_code,'service.ingress.input');assert.equal(finish.error_kind,'invalid_argument');assert.equal(finish.outcome,'failure');
+ const reclaimed=records.filter(e=>e.schema==='request-finalization/1'&&e.event==='request_task_reclaimed');assert.equal(reclaimed.length,1,'missing/duplicate task reclaim');
+ const released=records.filter(e=>e.schema==='request-finalization/1'&&e.event==='request_account_released');assert.equal(released.length,1,'missing physical release');
+ for(const e of [...reclaimed,...released]){assert.equal(e.process_instance,b.process_instance,'process ledger ownership');assert.equal(e.process_id,b.pid);for(const k of ['account_slot','account_generation','audit_generation'])assert.equal(e.account[k],b.account[k],'account ledger ownership '+k);}
+ assert.equal(reclaimed[0].completion,'failed');assert.equal(released[0].completion,'physically_released');assert.equal(released[0].account.healthy,true);
+ const boundaries=records.filter(e=>e.event==='request_failure_boundary');assert.equal(boundaries.length,1,'missing source rejection boundary');const boundary=boundaries[0];check({context:boundary.source_context});assert.equal(boundary.source_submission,'written');assert.equal(boundary.original_capture,'complete_written');
+ const originals=emergency.filter(e=>e.event==='request_error_original'&&e.channel==='context'&&e.state==='field_end'&&e.occurrence?.diagnostic_id===boundary.occurrence.diagnostic_id);assert.equal(originals.length,1,'missing source context');
+ const source=JSON.parse(originals[0].payload);assert.equal(source.context.requestInfo.requestId,i.requestId);assert.equal(source.context.requestInfo.callId,i.callId);assert.equal(source.context.traceInfo.traceId,i.traceInfo.traceId);assert.equal(source.context.traceInfo.rpcId,i.traceInfo.rpcId);assert.equal(source.context.requestInfo.localRequestId,[...locals][0]);assert.equal(source.context.executionInfo.taskId,[...tasks][0]);assert.equal(source.context.executionInfo.phase,'reading');assert.equal(source.facts.causes[0].stage,'request_decode');
+ const audits=emergency.filter(e=>e.event==='request_audit_passed'&&e.state==='record_complete').map(e=>JSON.parse(e.payload)).filter(e=>e.context?.requestInfo?.requestId===i.requestId);assert.equal(audits.length,1,'missing completed resource audit');const audit=audits[0];assert.equal(audit.context.requestInfo.callId,i.callId);assert.equal(audit.context.requestInfo.localRequestId,[...locals][0]);assert.equal(audit.context.traceInfo.traceId,i.traceInfo.traceId);assert.equal(audit.context.traceInfo.rpcId,i.traceInfo.rpcId);assert.equal(audit.context.executionInfo.phase,'reading');assert.equal(audit.context.executionInfo.taskId,[...tasks][0]);for(const k of ['account_slot','account_generation','audit_generation'])assert.equal(audit.audit[k],b.account[k],'audit account ownership');for(const k of ['outstanding_bytes','outstanding_objects','database_connections','database_operations','rpc_operations'])assert.equal(audit.audit[k],0,'resource audit '+k);assert.equal(audit.audit.storage_occupied,false);
+ return {phase:'input_decode_rejected',db:'not_applicable',scope:'not_established',reclaimed:true,physicallyReleased:true,events:related,account:b.account};
+}
+export function assertRouteRejection(actual,calls){assert.equal(actual.status,404,'wrong-app must be HTTP404');assert.notEqual(actual.body?.success,true);assert.equal(calls.length,0,'wrong-app made RPC');return {phase:'route_before_identity',rpc:'independent_mock_zero',requestReclamation:'unverified',handlerAttribution:'unverified',verified:false};}

package/tools/modules/backend/report.mjs

@@ -0,0 +1,13 @@
+export function classifyReport(report,selected){
+ const frameworkIds=new Set(selected.filter(s=>s.scope==='framework').map(s=>s.id));
+ const observations=report.scenarios.filter(s=>frameworkIds.has(s.id));
+ const business=selected.filter(s=>!frameworkIds.has(s.id));
+ report.scenarios=report.scenarios.filter(s=>!frameworkIds.has(s.id));
+ report.total=business.length;
+ for(const status of ['passed','failed','unverified'])report[status]=report.scenarios.filter(s=>s.status===status).length;
+ report.notRunIds=business.filter(s=>!report.scenarios.some(x=>x.id===s.id)).map(s=>s.id);
+ report.notRun=report.notRunIds.length;
+ report.framework={total:frameworkIds.size,observations,notRunIds:[...frameworkIds].filter(id=>!observations.some(s=>s.id===id)),scope:'outside-Spec-business-acceptance'};
+ report.status=report.infrastructureError||report.cleanupErrors?'infrastructure-failed':report.failed?'failed':report.notRun||report.unverified?'incomplete':'passed';
+ return report;
+}

package/tools/modules/backend/report.test.mjs

@@ -0,0 +1,13 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import {classifyReport} from './report.mjs';
+test('framework observations do not count as business acceptance or hide business failures',()=>{
+ const selected=[{id:'business'},{id:'wrong-app',scope:'framework'}];
+ for(const status of ['unverified','failed']){
+ const r=classifyReport({scenarios:[{id:'business',status:'passed'},{id:'wrong-app',status}]},selected);
+ assert.equal(r.total,1);assert.equal(r.passed,1);assert.equal(r.failed,0);assert.equal(r.unverified,0);assert.equal(r.status,'passed');assert.equal(r.framework.observations[0].status,status);
+ }
+ assert.equal(classifyReport({scenarios:[{id:'business',status:'failed'}]},selected).status,'failed');
+ assert.equal(classifyReport({scenarios:[]},selected).status,'incomplete');
+ assert.equal(classifyReport({scenarios:[{id:'business',status:'passed'}],cleanupErrors:[{}]},selected).status,'infrastructure-failed');
+});

package/tools/modules/backend/run.mjs

@@ -0,0 +1,50 @@
+import assert from 'node:assert/strict';
+import {resolve} from 'node:path';
+import {pathToFileURL} from 'node:url';
+import {mkdir,readFile,writeFile,access} from 'node:fs/promises';
+import {constants} from 'node:fs';
+import {createHash} from 'node:crypto';
+import {within,preflight} from './paths.mjs';
+import {scenarioActions} from './actions.mjs';
+import {mock} from './grpc.mjs';
+import {product} from './product.mjs';
+import {externalOutput,sleep} from './util.mjs';
+import {requestLogs} from './logs.mjs';
+import {assertRouteRejection} from './rejection-logs.mjs';
+import {classifyReport} from './report.mjs';
+export async function run({projectRoot,repositoryRoot,adapter,out,binary,caseId,list=false,identity}){
+ assert(projectRoot&&repositoryRoot&&adapter,'explicit project root, repository root and adapter required');
+ await within(repositoryRoot,projectRoot,'project');await within(projectRoot,adapter,'adapter');
+ const {project}=await import(pathToFileURL(resolve(adapter)));const config=await project(resolve(projectRoot));
+ assert(config.rpc?.serviceName&&config.proto&&config.process?.app&&config.process?.alias,'incomplete project protocol/process configuration');
+ assert.equal(typeof config.prepare,'function','controlled scenario plan required');
+ assert.equal(typeof config.execute,'function','controlled scenario action required');
+ await preflight({projectRoot,repositoryRoot,adapter,proto:config.proto,binary,list});
+ assert(Array.isArray(config.inputFiles)&&config.inputFiles.length,'explicit project input file closure required');
+ const projectInputs=[];for(const file of [...new Set([resolve(adapter),resolve(config.proto),...config.inputFiles.map(file=>resolve(file))])]){await within(repositoryRoot,file,'project input');projectInputs.push({file:file.slice(resolve(repositoryRoot).length+1),sha256:createHash('sha256').update(await readFile(file)).digest('hex')});}
+ const all=config.scenarios;assert(Array.isArray(all)&&all.length,'empty scenarios');assert.equal(new Set(all.map(s=>s.id)).size,all.length,'duplicate scene id');
+ const selected=caseId?all.filter(s=>s.id===caseId):all;assert(selected.length,'unknown case');
+ if(list){await new Promise(done=>process.stdout.write(JSON.stringify(all.map(({id,operation,basis,scope})=>({id,operation,basis,scope:scope??'business'})),null,2)+'\n',done));return;}
+ assert(binary&&out,'real binary and fresh external output required');await access(resolve(binary),constants.X_OK);await access(config.proto);const destination=externalOutput(repositoryRoot,out);
+ await mkdir(destination);const report={...config.frozen,tool:identity,projectInputs,scenarioSetSha256:createHash('sha256').update(JSON.stringify(all)).digest('hex'),started:new Date().toISOString(),scenarios:[],database:config.database};
+ let rpc,app,stage='startup';const abort=new AbortController();const listeners=new Map();
+ for(const signal of ['SIGINT','SIGTERM']){const handler=()=>{report.interrupted=signal;abort.abort();rpc?.release();};listeners.set(signal,handler);process.once(signal,handler);}
+ try{
+ report.binarySha256=createHash('sha256').update(await readFile(resolve(binary))).digest('hex');
+ rpc=await mock(config.proto,{...config.rpc,requireContext:true});
+ app=await product({...config.process,binary:resolve(binary),mock:rpc,out:resolve(destination,'product')});stage='business';
+ for(const s of selected){if(abort.signal.aborted)break;const dir=resolve(destination,s.id.replace(/[^\w.-]/g,'_'));await mkdir(dir);const e={id:s.id,basis:s.basis},pending=new Set();
+ try{
+ // Adapter receives only controlled actions. Every HTTP action registers a
+ // strict planned owner, every RPC uses wire/schema/parameter/count guards.
+ const controlled=scenarioActions({plan:config.prepare(s),rpc,app,abort,pending});
+ const result=await config.execute(s,{rpc:controlled.rpc,app:controlled.app,out:destination,abort,e,track:p=>{pending.add(p);p.catch(()=>{});},requestLogs:(directory,actual,options)=>requestLogs(directory,actual,{...options,database:config.databaseLogPolicy}),assertRouteRejection,sleep});
+ controlled.finish();
+ assert(['passed','unverified'].includes(result?.status),'invalid scenario result');report.scenarios.push({id:s.id,...result});
+ }catch(err){e.error=err.stack;report.scenarios.push({id:s.id,status:'failed',error:err.message});}
+ finally{rpc.release();await Promise.allSettled([...pending]);e.calls=structuredClone(rpc.records);e.ownership=rpc.expectations();e.violations=[...rpc.violations];await writeFile(resolve(dir,'evidence.json'),JSON.stringify(e,null,2));}
+ }
+ }catch(err){report.failureStage=stage;report.infrastructureError=err.stack;}
+ finally{for(const [name,resource]of [['product',app],['grpc',rpc]])if(resource)try{await resource.close();}catch(err){(report.cleanupErrors??=[]).push({name,error:err.message});}for(const [signal,handler]of listeners)process.removeListener(signal,handler);report.finished=new Date().toISOString();classifyReport(report,selected);await writeFile(resolve(destination,'report.json'),JSON.stringify(report,null,2));}
+ console.log(JSON.stringify(report));process.exitCode=report.status==='passed'?0:1;return report;
+}