@adhd/apigen-conformance 0.1.0

package/index.d.ts

@@ -0,0 +1,2 @@
+export { seg, makeOp, ROUND_TRIP_OP, DESCRIPTOR_VECTORS, roundTripOperation, assertOperationEqual, OP_UNSAFE_ACTION, OP_SAFE_QUERY, OP_COLLISION_A, OP_COLLISION_B, OP_DISTINCT_A, OP_DISTINCT_B, NAMING_VECTORS, assertUnsafeIsPost, assertSafeIsGet, assertCollisionDetected, assertNoCollision, ENVELOPE_CASES, ENVELOPE_VECTORS, assertEnvelopeBinding, ERROR_MAPPING_VECTORS, assertErrorMapping, assertApiErrorCodeSurvivesSerialize, VALIDATION_VECTORS, minimalSchemaValidate, runAllVectors, } from './lib/vectors';
+export type { ValidationCase, VectorResult } from './lib/vectors';

package/index.js

@@ -0,0 +1,3 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});function C(t){return t.words.join("-")}function x(t){return t.words.map(ie).join("")}function V(t){return t.words.join("_")}function _(t,e={}){var u,m;const n=[t.namespace,...t.path],r=t.safe?"GET":"POST",a=((m=(u=e.http)==null?void 0:u.verb)==null?void 0:m[t.id])??r,s="/"+n.map(d=>C(d)).join("/"),p=n.map(d=>V(d)).join("_"),c=n.map(d=>V(d)).slice(0,-1).join("."),f=x(n[n.length-2]??n[0]),h=x(n[n.length-1]),g=n.map(d=>C(d));return{http:{verb:a,route:s},mcp:{name:p},grpc:{package:c,service:f,method:h},cli:{path:g}}}class M extends Error{constructor(e){const n=e.map(r=>`  [${r.transport}] "${r.target}" ← ${r.ids[0]} vs ${r.ids[1]}`);super(`apigen-naming: ${e.length} projection collision(s) detected:
+${n.join(`
+`)}`),this.name="CollisionDetectedError",this.collisions=e}}function z(t,e={}){const n=new Map,r=new Map,a=new Map,s=new Map,p=[];for(const i of t){const c=_(i,e),f=`${c.http.verb} ${c.http.route}`,h=n.get(f);h!==void 0&&h!==i.id?p.push({transport:"http",target:f,ids:[h,i.id]}):n.set(f,i.id);const g=r.get(c.mcp.name);g!==void 0&&g!==i.id?p.push({transport:"mcp",target:c.mcp.name,ids:[g,i.id]}):r.set(c.mcp.name,i.id);const u=`${c.grpc.package}.${c.grpc.service}/${c.grpc.method}`,m=a.get(u);m!==void 0&&m!==i.id?p.push({transport:"grpc",target:u,ids:[m,i.id]}):a.set(u,i.id);const d=c.cli.path.join(" "),N=s.get(d);N!==void 0&&N!==i.id?p.push({transport:"cli",target:d,ids:[N,i.id]}):s.set(d,i.id)}if(p.length>0)throw new M(p)}function L(t,e){return`x-${t}-${e}`}function te(t,e){return`--${t}-${e}`}function ne(t,e){const n=r=>r.toUpperCase().replace(/-/g,"_");return t==="adhd"?`APIGEN_${n(e)}`:`APIGEN_${n(t)}_${n(e)}`}const re=L;function ie(t){return t.length===0?t:t[0].toUpperCase()+t.slice(1)}const R={invalid_argument:400,unauthenticated:401,permission_denied:403,not_found:404,internal:500},D={invalid_argument:"INVALID_ARGUMENT",unauthenticated:"UNAUTHENTICATED",permission_denied:"PERMISSION_DENIED",not_found:"NOT_FOUND",internal:"INTERNAL"},j={invalid_argument:2,unauthenticated:3,permission_denied:3,not_found:4,internal:1},G={invalid_argument:"error",unauthenticated:"error",permission_denied:"error",not_found:"error",internal:"error"};class se extends Error{constructor(e,n,r){super(n),this.name="ApiError",this.code=e,this.details=r,Object.setPrototypeOf(this,new.target.prototype)}toJSON(){const e={code:this.code,message:this.message};return this.details!==void 0&&(e.details=this.details),e}}function o(t,e){return{raw:t,words:e}}function l(t){return{host:"ts",kind:"action",async:!1,streaming:!1,safe:!1,input:{type:"object",properties:{}},output:{type:"object"},envelope:{},typeText:null,...t}}const U=l({id:"transform/humanize/humanize-bytes",host:"ts",namespace:o("transform",["transform"]),path:[o("humanize",["humanize"]),o("humanizeBytes",["humanize","bytes"])],kind:"action",async:!0,streaming:!1,safe:!1,input:{type:"object",properties:{bytes:{type:"number"},precision:{type:"number"}},required:["bytes"]},output:{type:"string"},envelope:{type:"object",properties:{session:{type:"string"}},required:["session"]},typeText:{lang:"ts",input:"{ bytes: number; precision?: number }",output:"string"}});function k(t){return JSON.parse(JSON.stringify(t))}function K(t,e){const n=JSON.stringify(t),r=JSON.stringify(e);if(n===r)return null;const a=Object.keys(t);for(const s of a)if(JSON.stringify(t[s])!==JSON.stringify(e[s]))return`field "${s}" differs: ${JSON.stringify(t[s])} !== ${JSON.stringify(e[s])}`;return"unexpected structural diff (key set mismatch)"}const w=[{id:"descriptor.roundtrip.1",description:"A complete Operation round-trips through JSON serialization losslessly",input:U},{id:"descriptor.roundtrip.2",description:"typeText: null is preserved (not dropped or coerced)",input:l({id:"transform/ping",namespace:o("transform",["transform"]),path:[o("ping",["ping"])],typeText:null})},{id:"descriptor.roundtrip.3",description:"Empty $defs in input schema is preserved",input:l({id:"transform/noop",namespace:o("transform",["transform"]),path:[o("noop",["noop"])],input:{type:"object",$defs:{},properties:{}}})}],T=o("auth",["auth"]),J=o("transform",["transform"]),F=o("session",["session"]),oe=o("login",["login"]),H=o("humanize",["humanize"]),q=o("humanizeBytes",["humanize","bytes"]),E=l({id:"transform/humanize/humanize-bytes",namespace:J,path:[H,q],safe:!1}),b=l({id:"transform/humanize/humanize-bytes-safe",namespace:J,path:[H,q],safe:!0}),A=l({id:"auth/session",namespace:T,path:[F],safe:!1}),P=l({id:"auth/login",namespace:T,path:[o("session",["session"])],safe:!1}),v=l({id:"auth/session",namespace:T,path:[F],safe:!1}),O=l({id:"auth/login",namespace:T,path:[oe],safe:!1});function B(t){const e=_(t);return e.http.verb!=="POST"?`expected verb POST for safe=false, got ${e.http.verb}`:null}function X(t){const e=_(t);return e.http.verb!=="GET"?`expected verb GET for safe=true, got ${e.http.verb}`:null}function Q(t){try{return z(t),"expected CollisionDetectedError to be thrown, but checkCollisions succeeded"}catch(e){return e instanceof M?null:`expected CollisionDetectedError, got: ${String(e)}`}}function S(t){try{return z(t),null}catch(e){return`expected no collision, but got: ${String(e)}`}}const ae=[{id:"naming.verb.1",description:"safe=false → HTTP verb is POST",op:E,expected:{httpVerb:"POST"}},{id:"naming.verb.2",description:"safe=true → HTTP verb is GET",op:b,expected:{httpVerb:"GET"}},{id:"naming.verb.NEGATIVE",description:"safe=false does NOT produce GET (negative control)",op:E,expected:{httpVerbIsNot:"GET"}},{id:"naming.collision.1",description:"Two ids with identical path tokenization → CollisionDetectedError",ops:[A,P],expected:{collision:!0}},{id:"naming.collision.2",description:"Distinct ops do NOT trigger collision",ops:[v,O],expected:{collision:!1}},{id:"naming.collision.NEGATIVE",description:"Non-colliding set must NOT throw (negative control)",ops:[v,O],expected:{collision:!1}}],$=[{pluginId:"auth",field:"session",expectedKey:"x-auth-session",expectedFlag:"--auth-session",expectedEnv:"APIGEN_AUTH_SESSION"},{pluginId:"adhd",field:"trace-id",expectedKey:"x-adhd-trace-id",expectedFlag:"--adhd-trace-id",expectedEnv:"APIGEN_TRACE_ID"},{pluginId:"rate",field:"limit",expectedKey:"x-rate-limit",expectedFlag:"--rate-limit",expectedEnv:"APIGEN_RATE_LIMIT"}];function Y(t,e,n,r,a){const s=L(t,e),p=te(t,e),i=ne(t,e),c=re(t,e);return s!==n?`envelopeKey: expected "${n}", got "${s}"`:p!==r?`envelopeCliFlag: expected "${r}", got "${p}"`:i!==a?`envelopeEnvVar: expected "${a}", got "${i}"`:c!==s?`envelopeMetaKey !== envelopeKey: "${c}" !== "${s}"`:null}const ce=$.map(t=>({id:`envelope.binding.${t.pluginId}.${t.field.replace(/-/g,"_")}`,description:`(${t.pluginId}, ${t.field}) → correct carrier key for all transports`,pluginId:t.pluginId,field:t.field,expected:{httpHeader:t.expectedKey,grpcMeta:t.expectedKey,mcpMetaKey:t.expectedKey,cliFlag:t.expectedFlag,cliEnvVar:t.expectedEnv}})),y=[{id:"error.map.invalid_argument",code:"invalid_argument",expected:{http:400,grpc:"INVALID_ARGUMENT",cli:2,mcp:"error"}},{id:"error.map.unauthenticated",code:"unauthenticated",expected:{http:401,grpc:"UNAUTHENTICATED",cli:3,mcp:"error"}},{id:"error.map.permission_denied",code:"permission_denied",expected:{http:403,grpc:"PERMISSION_DENIED",cli:3,mcp:"error"}},{id:"error.map.not_found",code:"not_found",expected:{http:404,grpc:"NOT_FOUND",cli:4,mcp:"error"}},{id:"error.map.internal",code:"internal",expected:{http:500,grpc:"INTERNAL",cli:1,mcp:"error"}}];function Z(t,e){return R[t]!==e.http?`HTTP_STATUS[${t}]: expected ${e.http}, got ${R[t]}`:D[t]!==e.grpc?`GRPC_CODE[${t}]: expected "${e.grpc}", got "${D[t]}"`:j[t]!==e.cli?`CLI_EXIT_CODE[${t}]: expected ${e.cli}, got ${j[t]}`:G[t]!==e.mcp?`MCP_ERROR_KIND[${t}]: expected "${e.mcp}", got "${G[t]}"`:null}function W(t){const n=new se(t,"test message").toJSON();return n.code!==t?`ApiError.toJSON().code: expected "${t}", got "${n.code}"`:null}const ee=[{id:"validation.extra-properties",description:"additionalProperties not restricted — extra keys pass schema but may cause dispatch errors",schema:{type:"object",properties:{userId:{type:"string"}},required:["userId"]},schemaValidValue:{userId:"abc",unexpectedField:"injection"},domainNote:"An unexpected field passes the schema but may be ignored or cause a typed dispatch error in strict hosts (Rust/Go)."},{id:"validation.number-precision",description:"A JSON number within the schema range but beyond JS safe integer boundary",schema:{type:"object",properties:{amount:{type:"integer"}},required:["amount"]},schemaValidValue:{amount:9007199254740992},domainNote:"Exceeds Number.MAX_SAFE_INTEGER; JSON.parse silently rounds it. SPEC §4 mandates int64 as string-encoded for 64-bit integers; this proves the validator alone cannot catch the precision loss."},{id:"validation.date-string",description:"A date-format string is schema-valid but semantically wrong",schema:{type:"object",properties:{at:{type:"string",format:"date-time"}},required:["at"]},schemaValidValue:{at:"2099-02-30T00:00:00Z"},domainNote:"Standard AJV does not validate date-time values by default; Feb 30 passes schema validation but is a semantically invalid date."},{id:"validation.option-vs-missing",description:"An Option/nullable field being null passes where a domain function expects presence",schema:{type:"object",properties:{user:{oneOf:[{type:"object",properties:{id:{type:"string"}}},{type:"null"}]}},required:["user"]},schemaValidValue:{user:null},domainNote:"null satisfies the oneOf schema, but a domain function that destructures user.id will throw at runtime — validation passed, dispatch fails."}];function I(t,e){if(t.type==="object"){if(typeof e!="object"||e===null)return!1;const n=t.required;if(n){const r=e;for(const a of n)if(!(a in r))return!1}return!0}return e!==void 0}function pe(){const t=[];for(const e of w){const n=k(e.input),r=K(e.input,n);t.push({id:e.id,pass:r===null,error:r??void 0})}{const e=B(E);t.push({id:"naming.verb.1",pass:e===null,error:e??void 0})}{const e=X(b);t.push({id:"naming.verb.2",pass:e===null,error:e??void 0})}{const n=_(E).http.verb!=="GET";t.push({id:"naming.verb.NEGATIVE",pass:n,error:n?void 0:"safe=false produced GET (should be POST)"})}{const e=Q([A,P]);t.push({id:"naming.collision.1",pass:e===null,error:e??void 0})}{const e=S([v,O]);t.push({id:"naming.collision.2",pass:e===null,error:e??void 0})}{const e=S([v,O]);t.push({id:"naming.collision.NEGATIVE",pass:e===null,error:e??void 0})}for(const e of $){const n=`envelope.binding.${e.pluginId}.${e.field.replace(/-/g,"_")}`,r=Y(e.pluginId,e.field,e.expectedKey,e.expectedFlag,e.expectedEnv);t.push({id:n,pass:r===null,error:r??void 0})}for(const e of y){const n=Z(e.code,e.expected);t.push({id:e.id,pass:n===null,error:n??void 0})}for(const e of y){const n=`${e.id}.serialize`,r=W(e.code);t.push({id:n,pass:r===null,error:r??void 0})}for(const e of ee){const n=I(e.schema,e.schemaValidValue);t.push({id:e.id,pass:n,error:n?void 0:`schema validator rejected a schema-valid value (should have accepted): ${JSON.stringify(e.schemaValidValue)}`});const r=`${e.id}.NEGATIVE`,a=!I(e.schema,"not-an-object");t.push({id:r,pass:a,error:a?void 0:'schema validator accepted "not-an-object" as valid for an object schema'})}return t}exports.DESCRIPTOR_VECTORS=w;exports.ENVELOPE_CASES=$;exports.ENVELOPE_VECTORS=ce;exports.ERROR_MAPPING_VECTORS=y;exports.NAMING_VECTORS=ae;exports.OP_COLLISION_A=A;exports.OP_COLLISION_B=P;exports.OP_DISTINCT_A=v;exports.OP_DISTINCT_B=O;exports.OP_SAFE_QUERY=b;exports.OP_UNSAFE_ACTION=E;exports.ROUND_TRIP_OP=U;exports.VALIDATION_VECTORS=ee;exports.assertApiErrorCodeSurvivesSerialize=W;exports.assertCollisionDetected=Q;exports.assertEnvelopeBinding=Y;exports.assertErrorMapping=Z;exports.assertNoCollision=S;exports.assertOperationEqual=K;exports.assertSafeIsGet=X;exports.assertUnsafeIsPost=B;exports.makeOp=l;exports.minimalSchemaValidate=I;exports.roundTripOperation=k;exports.runAllVectors=pe;exports.seg=o;

package/index.mjs

@@ -0,0 +1,456 @@
+function _(t) {
+  return t.words.join("-");
+}
+function O(t) {
+  return t.words.map(q).join("");
+}
+function S(t) {
+  return t.words.join("_");
+}
+function b(t, e = {}) {
+  var u, m;
+  const n = [t.namespace, ...t.path], r = t.safe ? "GET" : "POST", o = ((m = (u = e.http) == null ? void 0 : u.verb) == null ? void 0 : m[t.id]) ?? r, s = "/" + n.map((d) => _(d)).join("/"), p = n.map((d) => S(d)).join("_"), a = n.map((d) => S(d)).slice(0, -1).join("."), f = O(n[n.length - 2] ?? n[0]), h = O(n[n.length - 1]), g = n.map((d) => _(d));
+  return {
+    http: { verb: o, route: s },
+    mcp: { name: p },
+    grpc: { package: a, service: f, method: h },
+    cli: { path: g }
+  };
+}
+class j extends Error {
+  constructor(e) {
+    const n = e.map(
+      (r) => `  [${r.transport}] "${r.target}" ← ${r.ids[0]} vs ${r.ids[1]}`
+    );
+    super(`apigen-naming: ${e.length} projection collision(s) detected:
+${n.join(`
+`)}`), this.name = "CollisionDetectedError", this.collisions = e;
+  }
+}
+function R(t, e = {}) {
+  const n = /* @__PURE__ */ new Map(), r = /* @__PURE__ */ new Map(), o = /* @__PURE__ */ new Map(), s = /* @__PURE__ */ new Map(), p = [];
+  for (const i of t) {
+    const a = b(i, e), f = `${a.http.verb} ${a.http.route}`, h = n.get(f);
+    h !== void 0 && h !== i.id ? p.push({ transport: "http", target: f, ids: [h, i.id] }) : n.set(f, i.id);
+    const g = r.get(a.mcp.name);
+    g !== void 0 && g !== i.id ? p.push({ transport: "mcp", target: a.mcp.name, ids: [g, i.id] }) : r.set(a.mcp.name, i.id);
+    const u = `${a.grpc.package}.${a.grpc.service}/${a.grpc.method}`, m = o.get(u);
+    m !== void 0 && m !== i.id ? p.push({ transport: "grpc", target: u, ids: [m, i.id] }) : o.set(u, i.id);
+    const d = a.cli.path.join(" "), N = s.get(d);
+    N !== void 0 && N !== i.id ? p.push({ transport: "cli", target: d, ids: [N, i.id] }) : s.set(d, i.id);
+  }
+  if (p.length > 0)
+    throw new j(p);
+}
+function D(t, e) {
+  return `x-${t}-${e}`;
+}
+function L(t, e) {
+  return `--${t}-${e}`;
+}
+function F(t, e) {
+  const n = (r) => r.toUpperCase().replace(/-/g, "_");
+  return t === "adhd" ? `APIGEN_${n(e)}` : `APIGEN_${n(t)}_${n(e)}`;
+}
+const H = D;
+function q(t) {
+  return t.length === 0 ? t : t[0].toUpperCase() + t.slice(1);
+}
+const I = {
+  invalid_argument: 400,
+  unauthenticated: 401,
+  permission_denied: 403,
+  not_found: 404,
+  internal: 500
+}, $ = {
+  invalid_argument: "INVALID_ARGUMENT",
+  unauthenticated: "UNAUTHENTICATED",
+  permission_denied: "PERMISSION_DENIED",
+  not_found: "NOT_FOUND",
+  internal: "INTERNAL"
+}, x = {
+  invalid_argument: 2,
+  unauthenticated: 3,
+  permission_denied: 3,
+  not_found: 4,
+  internal: 1
+}, A = {
+  invalid_argument: "error",
+  unauthenticated: "error",
+  permission_denied: "error",
+  not_found: "error",
+  internal: "error"
+};
+class B extends Error {
+  constructor(e, n, r) {
+    super(n), this.name = "ApiError", this.code = e, this.details = r, Object.setPrototypeOf(this, new.target.prototype);
+  }
+  /** Serialise to a plain object suitable for JSON transport. */
+  toJSON() {
+    const e = {
+      code: this.code,
+      message: this.message
+    };
+    return this.details !== void 0 && (e.details = this.details), e;
+  }
+}
+function c(t, e) {
+  return { raw: t, words: e };
+}
+function l(t) {
+  return {
+    host: "ts",
+    kind: "action",
+    async: !1,
+    streaming: !1,
+    safe: !1,
+    input: { type: "object", properties: {} },
+    output: { type: "object" },
+    envelope: {},
+    typeText: null,
+    ...t
+  };
+}
+const X = l({
+  id: "transform/humanize/humanize-bytes",
+  host: "ts",
+  namespace: c("transform", ["transform"]),
+  path: [c("humanize", ["humanize"]), c("humanizeBytes", ["humanize", "bytes"])],
+  kind: "action",
+  async: !0,
+  streaming: !1,
+  safe: !1,
+  input: {
+    type: "object",
+    properties: {
+      bytes: { type: "number" },
+      precision: { type: "number" }
+    },
+    required: ["bytes"]
+  },
+  output: { type: "string" },
+  envelope: {
+    type: "object",
+    properties: {
+      session: { type: "string" }
+    },
+    required: ["session"]
+  },
+  typeText: { lang: "ts", input: "{ bytes: number; precision?: number }", output: "string" }
+});
+function Q(t) {
+  return JSON.parse(JSON.stringify(t));
+}
+function Y(t, e) {
+  const n = JSON.stringify(t), r = JSON.stringify(e);
+  if (n === r)
+    return null;
+  const o = Object.keys(t);
+  for (const s of o)
+    if (JSON.stringify(t[s]) !== JSON.stringify(e[s]))
+      return `field "${s}" differs: ${JSON.stringify(t[s])} !== ${JSON.stringify(e[s])}`;
+  return "unexpected structural diff (key set mismatch)";
+}
+const Z = [
+  {
+    id: "descriptor.roundtrip.1",
+    description: "A complete Operation round-trips through JSON serialization losslessly",
+    input: X
+  },
+  {
+    id: "descriptor.roundtrip.2",
+    description: "typeText: null is preserved (not dropped or coerced)",
+    input: l({
+      id: "transform/ping",
+      namespace: c("transform", ["transform"]),
+      path: [c("ping", ["ping"])],
+      typeText: null
+    })
+  },
+  {
+    id: "descriptor.roundtrip.3",
+    description: "Empty $defs in input schema is preserved",
+    input: l({
+      id: "transform/noop",
+      namespace: c("transform", ["transform"]),
+      path: [c("noop", ["noop"])],
+      input: { type: "object", $defs: {}, properties: {} }
+    })
+  }
+], T = c("auth", ["auth"]), G = c("transform", ["transform"]), z = c("session", ["session"]), W = c("login", ["login"]), M = c("humanize", ["humanize"]), K = c("humanizeBytes", ["humanize", "bytes"]), v = l({
+  id: "transform/humanize/humanize-bytes",
+  namespace: G,
+  path: [M, K],
+  safe: !1
+}), U = l({
+  id: "transform/humanize/humanize-bytes-safe",
+  namespace: G,
+  path: [M, K],
+  safe: !0
+}), k = l({
+  id: "auth/session",
+  namespace: T,
+  path: [z],
+  safe: !1
+}), w = l({
+  id: "auth/login",
+  namespace: T,
+  path: [c("session", ["session"])],
+  // same words as segSession → collision
+  safe: !1
+}), E = l({
+  id: "auth/session",
+  namespace: T,
+  path: [z],
+  safe: !1
+}), y = l({
+  id: "auth/login",
+  namespace: T,
+  path: [W],
+  safe: !1
+});
+function ee(t) {
+  const e = b(t);
+  return e.http.verb !== "POST" ? `expected verb POST for safe=false, got ${e.http.verb}` : null;
+}
+function te(t) {
+  const e = b(t);
+  return e.http.verb !== "GET" ? `expected verb GET for safe=true, got ${e.http.verb}` : null;
+}
+function ne(t) {
+  try {
+    return R(t), "expected CollisionDetectedError to be thrown, but checkCollisions succeeded";
+  } catch (e) {
+    return e instanceof j ? null : `expected CollisionDetectedError, got: ${String(e)}`;
+  }
+}
+function P(t) {
+  try {
+    return R(t), null;
+  } catch (e) {
+    return `expected no collision, but got: ${String(e)}`;
+  }
+}
+const ae = [
+  {
+    id: "naming.verb.1",
+    description: "safe=false → HTTP verb is POST",
+    op: v,
+    expected: { httpVerb: "POST" }
+  },
+  {
+    id: "naming.verb.2",
+    description: "safe=true → HTTP verb is GET",
+    op: U,
+    expected: { httpVerb: "GET" }
+  },
+  {
+    id: "naming.verb.NEGATIVE",
+    description: "safe=false does NOT produce GET (negative control)",
+    op: v,
+    expected: { httpVerbIsNot: "GET" }
+  },
+  {
+    id: "naming.collision.1",
+    description: "Two ids with identical path tokenization → CollisionDetectedError",
+    ops: [k, w],
+    expected: { collision: !0 }
+  },
+  {
+    id: "naming.collision.2",
+    description: "Distinct ops do NOT trigger collision",
+    ops: [E, y],
+    expected: { collision: !1 }
+  },
+  {
+    id: "naming.collision.NEGATIVE",
+    description: "Non-colliding set must NOT throw (negative control)",
+    ops: [E, y],
+    expected: { collision: !1 }
+  }
+], J = [
+  { pluginId: "auth", field: "session", expectedKey: "x-auth-session", expectedFlag: "--auth-session", expectedEnv: "APIGEN_AUTH_SESSION" },
+  { pluginId: "adhd", field: "trace-id", expectedKey: "x-adhd-trace-id", expectedFlag: "--adhd-trace-id", expectedEnv: "APIGEN_TRACE_ID" },
+  { pluginId: "rate", field: "limit", expectedKey: "x-rate-limit", expectedFlag: "--rate-limit", expectedEnv: "APIGEN_RATE_LIMIT" }
+];
+function re(t, e, n, r, o) {
+  const s = D(t, e), p = L(t, e), i = F(t, e), a = H(t, e);
+  return s !== n ? `envelopeKey: expected "${n}", got "${s}"` : p !== r ? `envelopeCliFlag: expected "${r}", got "${p}"` : i !== o ? `envelopeEnvVar: expected "${o}", got "${i}"` : a !== s ? `envelopeMetaKey !== envelopeKey: "${a}" !== "${s}"` : null;
+}
+const ce = J.map((t) => ({
+  id: `envelope.binding.${t.pluginId}.${t.field.replace(/-/g, "_")}`,
+  description: `(${t.pluginId}, ${t.field}) → correct carrier key for all transports`,
+  pluginId: t.pluginId,
+  field: t.field,
+  expected: {
+    httpHeader: t.expectedKey,
+    grpcMeta: t.expectedKey,
+    mcpMetaKey: t.expectedKey,
+    cliFlag: t.expectedFlag,
+    cliEnvVar: t.expectedEnv
+  }
+})), C = [
+  { id: "error.map.invalid_argument", code: "invalid_argument", expected: { http: 400, grpc: "INVALID_ARGUMENT", cli: 2, mcp: "error" } },
+  { id: "error.map.unauthenticated", code: "unauthenticated", expected: { http: 401, grpc: "UNAUTHENTICATED", cli: 3, mcp: "error" } },
+  { id: "error.map.permission_denied", code: "permission_denied", expected: { http: 403, grpc: "PERMISSION_DENIED", cli: 3, mcp: "error" } },
+  { id: "error.map.not_found", code: "not_found", expected: { http: 404, grpc: "NOT_FOUND", cli: 4, mcp: "error" } },
+  { id: "error.map.internal", code: "internal", expected: { http: 500, grpc: "INTERNAL", cli: 1, mcp: "error" } }
+];
+function ie(t, e) {
+  return I[t] !== e.http ? `HTTP_STATUS[${t}]: expected ${e.http}, got ${I[t]}` : $[t] !== e.grpc ? `GRPC_CODE[${t}]: expected "${e.grpc}", got "${$[t]}"` : x[t] !== e.cli ? `CLI_EXIT_CODE[${t}]: expected ${e.cli}, got ${x[t]}` : A[t] !== e.mcp ? `MCP_ERROR_KIND[${t}]: expected "${e.mcp}", got "${A[t]}"` : null;
+}
+function se(t) {
+  const n = new B(t, "test message").toJSON();
+  return n.code !== t ? `ApiError.toJSON().code: expected "${t}", got "${n.code}"` : null;
+}
+const oe = [
+  {
+    id: "validation.extra-properties",
+    description: "additionalProperties not restricted — extra keys pass schema but may cause dispatch errors",
+    schema: {
+      type: "object",
+      properties: { userId: { type: "string" } },
+      required: ["userId"]
+    },
+    schemaValidValue: { userId: "abc", unexpectedField: "injection" },
+    domainNote: "An unexpected field passes the schema but may be ignored or cause a typed dispatch error in strict hosts (Rust/Go)."
+  },
+  {
+    id: "validation.number-precision",
+    description: "A JSON number within the schema range but beyond JS safe integer boundary",
+    schema: {
+      type: "object",
+      properties: { amount: { type: "integer" } },
+      required: ["amount"]
+    },
+    // This exceeds Number.MAX_SAFE_INTEGER — JSON.parse will silently corrupt it.
+    schemaValidValue: { amount: 9007199254740992 },
+    domainNote: "Exceeds Number.MAX_SAFE_INTEGER; JSON.parse silently rounds it. SPEC §4 mandates int64 as string-encoded for 64-bit integers; this proves the validator alone cannot catch the precision loss."
+  },
+  {
+    id: "validation.date-string",
+    description: "A date-format string is schema-valid but semantically wrong",
+    schema: {
+      type: "object",
+      properties: { at: { type: "string", format: "date-time" } },
+      required: ["at"]
+    },
+    schemaValidValue: { at: "2099-02-30T00:00:00Z" },
+    // Feb 30 does not exist
+    domainNote: "Standard AJV does not validate date-time values by default; Feb 30 passes schema validation but is a semantically invalid date."
+  },
+  {
+    id: "validation.option-vs-missing",
+    description: "An Option/nullable field being null passes where a domain function expects presence",
+    schema: {
+      type: "object",
+      properties: {
+        user: { oneOf: [{ type: "object", properties: { id: { type: "string" } } }, { type: "null" }] }
+      },
+      required: ["user"]
+    },
+    schemaValidValue: { user: null },
+    domainNote: "null satisfies the oneOf schema, but a domain function that destructures user.id will throw at runtime — validation passed, dispatch fails."
+  }
+];
+function V(t, e) {
+  if (t.type === "object") {
+    if (typeof e != "object" || e === null)
+      return !1;
+    const n = t.required;
+    if (n) {
+      const r = e;
+      for (const o of n)
+        if (!(o in r))
+          return !1;
+    }
+    return !0;
+  }
+  return e !== void 0;
+}
+function pe() {
+  const t = [];
+  for (const e of Z) {
+    const n = Q(e.input), r = Y(e.input, n);
+    t.push({ id: e.id, pass: r === null, error: r ?? void 0 });
+  }
+  {
+    const e = ee(v);
+    t.push({ id: "naming.verb.1", pass: e === null, error: e ?? void 0 });
+  }
+  {
+    const e = te(U);
+    t.push({ id: "naming.verb.2", pass: e === null, error: e ?? void 0 });
+  }
+  {
+    const n = b(v).http.verb !== "GET";
+    t.push({ id: "naming.verb.NEGATIVE", pass: n, error: n ? void 0 : "safe=false produced GET (should be POST)" });
+  }
+  {
+    const e = ne([k, w]);
+    t.push({ id: "naming.collision.1", pass: e === null, error: e ?? void 0 });
+  }
+  {
+    const e = P([E, y]);
+    t.push({ id: "naming.collision.2", pass: e === null, error: e ?? void 0 });
+  }
+  {
+    const e = P([E, y]);
+    t.push({ id: "naming.collision.NEGATIVE", pass: e === null, error: e ?? void 0 });
+  }
+  for (const e of J) {
+    const n = `envelope.binding.${e.pluginId}.${e.field.replace(/-/g, "_")}`, r = re(e.pluginId, e.field, e.expectedKey, e.expectedFlag, e.expectedEnv);
+    t.push({ id: n, pass: r === null, error: r ?? void 0 });
+  }
+  for (const e of C) {
+    const n = ie(e.code, e.expected);
+    t.push({ id: e.id, pass: n === null, error: n ?? void 0 });
+  }
+  for (const e of C) {
+    const n = `${e.id}.serialize`, r = se(e.code);
+    t.push({ id: n, pass: r === null, error: r ?? void 0 });
+  }
+  for (const e of oe) {
+    const n = V(e.schema, e.schemaValidValue);
+    t.push({
+      id: e.id,
+      pass: n,
+      error: n ? void 0 : `schema validator rejected a schema-valid value (should have accepted): ${JSON.stringify(e.schemaValidValue)}`
+    });
+    const r = `${e.id}.NEGATIVE`, o = !V(e.schema, "not-an-object");
+    t.push({
+      id: r,
+      pass: o,
+      error: o ? void 0 : 'schema validator accepted "not-an-object" as valid for an object schema'
+    });
+  }
+  return t;
+}
+export {
+  Z as DESCRIPTOR_VECTORS,
+  J as ENVELOPE_CASES,
+  ce as ENVELOPE_VECTORS,
+  C as ERROR_MAPPING_VECTORS,
+  ae as NAMING_VECTORS,
+  k as OP_COLLISION_A,
+  w as OP_COLLISION_B,
+  E as OP_DISTINCT_A,
+  y as OP_DISTINCT_B,
+  U as OP_SAFE_QUERY,
+  v as OP_UNSAFE_ACTION,
+  X as ROUND_TRIP_OP,
+  oe as VALIDATION_VECTORS,
+  se as assertApiErrorCodeSurvivesSerialize,
+  ne as assertCollisionDetected,
+  re as assertEnvelopeBinding,
+  ie as assertErrorMapping,
+  P as assertNoCollision,
+  Y as assertOperationEqual,
+  te as assertSafeIsGet,
+  ee as assertUnsafeIsPost,
+  l as makeOp,
+  V as minimalSchemaValidate,
+  Q as roundTripOperation,
+  pe as runAllVectors,
+  c as seg
+};

package/lib/vectors.d.ts

@@ -0,0 +1,221 @@
+import { ApiErrorCode } from '@adhd/apigen-errors';
+import { Operation, Segment } from '@adhd/apigen-core';
+
+/** Build a casing-neutral Segment from a raw token and its word list. */
+export declare function seg(raw: string, words: string[]): Segment;
+/**
+ * Build a minimal but complete Operation.
+ *
+ * Only the fields tested by a given vector are semantically meaningful;
+ * the rest are set to neutral defaults. This mirrors the approach used in
+ * `packages/apigen/naming/src/test/naming.spec.ts`.
+ */
+export declare function makeOp(overrides: Partial<Operation> & Pick<Operation, 'id' | 'namespace' | 'path'>): Operation;
+/** The reference Operation used across descriptor round-trip vectors. */
+export declare const ROUND_TRIP_OP: Operation;
+/**
+ * Serialize an Operation to a JSON string and deserialize it back.
+ *
+ * A host runner uses this to prove the descriptor survives its IPC wire
+ * (§14: extractor subprocess emits JSON; the CLI merges it). The round-trip
+ * MUST be lossless for all spec-defined fields.
+ */
+export declare function roundTripOperation(op: Operation): Operation;
+/**
+ * Assert that two Operations are deep-equal on every SPEC §4 field.
+ *
+ * Returns `null` on success; returns a string describing the first mismatch
+ * on failure (so non-TS hosts can surface useful diagnostics).
+ */
+export declare function assertOperationEqual(a: Operation, b: Operation): null | string;
+export declare const DESCRIPTOR_VECTORS: readonly [{
+    readonly id: "descriptor.roundtrip.1";
+    readonly description: "A complete Operation round-trips through JSON serialization losslessly";
+    readonly input: Operation;
+}, {
+    readonly id: "descriptor.roundtrip.2";
+    readonly description: "typeText: null is preserved (not dropped or coerced)";
+    readonly input: Operation;
+}, {
+    readonly id: "descriptor.roundtrip.3";
+    readonly description: "Empty $defs in input schema is preserved";
+    readonly input: Operation;
+}];
+/** unsafe action (safe=false): POST /transform/humanize/humanize-bytes */
+export declare const OP_UNSAFE_ACTION: Operation;
+/** safe query (safe=true): GET /transform/humanize/humanize-bytes */
+export declare const OP_SAFE_QUERY: Operation;
+/**
+ * Two operations whose `path` tokenization is identical — they will collide
+ * in every transport. Used for the collision negative-control.
+ *
+ * Op A: id='auth/session' path=[session]
+ * Op B: id='auth/login'   path=[session]  ← same segment words despite different id
+ */
+export declare const OP_COLLISION_A: Operation;
+export declare const OP_COLLISION_B: Operation;
+export declare const OP_DISTINCT_A: Operation;
+export declare const OP_DISTINCT_B: Operation;
+/** Assert that an Operation with safe=false projects to POST over HTTP. */
+export declare function assertUnsafeIsPost(op: Operation): null | string;
+/** Assert that an Operation with safe=true projects to GET over HTTP. */
+export declare function assertSafeIsGet(op: Operation): null | string;
+/**
+ * Assert that checkCollisions throws CollisionDetectedError for a colliding pair.
+ *
+ * Returns `null` on success (i.e. the error WAS thrown); returns a diagnostic
+ * string if the expected error was NOT thrown.
+ */
+export declare function assertCollisionDetected(ops: Operation[]): null | string;
+/**
+ * Assert that checkCollisions does NOT throw for a non-colliding set.
+ */
+export declare function assertNoCollision(ops: Operation[]): null | string;
+export declare const NAMING_VECTORS: readonly [{
+    readonly id: "naming.verb.1";
+    readonly description: "safe=false → HTTP verb is POST";
+    readonly op: Operation;
+    readonly expected: {
+        readonly httpVerb: "POST";
+    };
+}, {
+    readonly id: "naming.verb.2";
+    readonly description: "safe=true → HTTP verb is GET";
+    readonly op: Operation;
+    readonly expected: {
+        readonly httpVerb: "GET";
+    };
+}, {
+    readonly id: "naming.verb.NEGATIVE";
+    readonly description: "safe=false does NOT produce GET (negative control)";
+    readonly op: Operation;
+    readonly expected: {
+        readonly httpVerbIsNot: "GET";
+    };
+}, {
+    readonly id: "naming.collision.1";
+    readonly description: "Two ids with identical path tokenization → CollisionDetectedError";
+    readonly ops: readonly [Operation, Operation];
+    readonly expected: {
+        readonly collision: true;
+    };
+}, {
+    readonly id: "naming.collision.2";
+    readonly description: "Distinct ops do NOT trigger collision";
+    readonly ops: readonly [Operation, Operation];
+    readonly expected: {
+        readonly collision: false;
+    };
+}, {
+    readonly id: "naming.collision.NEGATIVE";
+    readonly description: "Non-colliding set must NOT throw (negative control)";
+    readonly ops: readonly [Operation, Operation];
+    readonly expected: {
+        readonly collision: false;
+    };
+}];
+/** Representative envelope field cases. */
+export declare const ENVELOPE_CASES: readonly [{
+    readonly pluginId: "auth";
+    readonly field: "session";
+    readonly expectedKey: "x-auth-session";
+    readonly expectedFlag: "--auth-session";
+    readonly expectedEnv: "APIGEN_AUTH_SESSION";
+}, {
+    readonly pluginId: "adhd";
+    readonly field: "trace-id";
+    readonly expectedKey: "x-adhd-trace-id";
+    readonly expectedFlag: "--adhd-trace-id";
+    readonly expectedEnv: "APIGEN_TRACE_ID";
+}, {
+    readonly pluginId: "rate";
+    readonly field: "limit";
+    readonly expectedKey: "x-rate-limit";
+    readonly expectedFlag: "--rate-limit";
+    readonly expectedEnv: "APIGEN_RATE_LIMIT";
+}];
+/**
+ * Assert envelope binding for a single (pluginId, field) pair.
+ *
+ * Returns `null` on full success; returns a diagnostic string on the first failure.
+ */
+export declare function assertEnvelopeBinding(pluginId: string, field: string, expectedKey: string, expectedFlag: string, expectedEnv: string): null | string;
+export declare const ENVELOPE_VECTORS: {
+    id: string;
+    description: string;
+    pluginId: "adhd" | "auth" | "rate";
+    field: "session" | "trace-id" | "limit";
+    expected: {
+        httpHeader: "x-auth-session" | "x-adhd-trace-id" | "x-rate-limit";
+        grpcMeta: "x-auth-session" | "x-adhd-trace-id" | "x-rate-limit";
+        mcpMetaKey: "x-auth-session" | "x-adhd-trace-id" | "x-rate-limit";
+        cliFlag: "--auth-session" | "--adhd-trace-id" | "--rate-limit";
+        cliEnvVar: "APIGEN_AUTH_SESSION" | "APIGEN_TRACE_ID" | "APIGEN_RATE_LIMIT";
+    };
+}[];
+/** The normative §9 mapping table expressed as plain data. */
+export declare const ERROR_MAPPING_VECTORS: Array<{
+    id: string;
+    code: ApiErrorCode;
+    expected: {
+        http: number;
+        grpc: string;
+        cli: number;
+        mcp: 'error';
+    };
+}>;
+/**
+ * Assert that a given ApiErrorCode maps to the expected transport statuses.
+ *
+ * Returns `null` on success; diagnostic string on first failure.
+ */
+export declare function assertErrorMapping(code: ApiErrorCode, expected: {
+    http: number;
+    grpc: string;
+    cli: number;
+    mcp: 'error';
+}): null | string;
+/**
+ * Assert that ApiError is constructible with the given code and that its code
+ * field survives serialization (toJSON) — the carrier shape shipped over every
+ * transport must round-trip the code.
+ */
+export declare function assertApiErrorCodeSurvivesSerialize(code: ApiErrorCode): null | string;
+/**
+ * A validation case: a JSON Schema + a value that is schema-valid.
+ * A host validator MUST accept this value without error.
+ *
+ * The `domainNote` explains why the value is still "wrong" at the domain level —
+ * this is the "necessary-not-sufficient" proof.
+ */
+export interface ValidationCase {
+    id: string;
+    description: string;
+    schema: Record<string, unknown>;
+    /** A value that satisfies the JSON Schema but may be wrong at domain level. */
+    schemaValidValue: unknown;
+    /** Why the value is still problematic despite passing schema validation. */
+    domainNote: string;
+}
+export declare const VALIDATION_VECTORS: ValidationCase[];
+/**
+ * A minimal JSON-Schema validator that checks the type keyword and required
+ * fields only — sufficient to prove "schema-valid-but-domain-wrong" for the
+ * vectors above without pulling in a full AJV dependency.
+ *
+ * Returns `true` if the value passes this minimal check, `false` otherwise.
+ *
+ * HOST RUNNERS: replace this with your host's real schema validator (AJV /
+ * pydantic / schemars). The point is that the real validator ALSO accepts
+ * these values, so the host's typed dispatch is the authoritative gate.
+ */
+export declare function minimalSchemaValidate(schema: Record<string, unknown>, value: unknown): boolean;
+/** A single vector result. */
+export interface VectorResult {
+    id: string;
+    pass: boolean;
+    /** Populated on failure with a diagnostic string. */
+    error?: string;
+}
+/** Execute all conformance vectors and return per-vector results. */
+export declare function runAllVectors(): VectorResult[];

package/package.json

@@ -0,0 +1,10 @@
+{
+  "name": "@adhd/apigen-conformance",
+  "version": "0.1.0",
+  "main": "./index.js",
+  "module": "./index.mjs",
+  "typings": "./index.d.ts",
+  "publishConfig": {
+    "access": "public"
+  }
+}