agentskeptic 1.2.1 → 1.4.0

package/schemas/registry-draft-response-v2.schema.json

@@ -0,0 +1,52 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://agentskeptic.com/schemas/registry-draft-response-v2.schema.json",
+  "title": "RegistryDraftResponseEnvelopeV2",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "draft", "assumptions", "warnings", "disclaimer", "model", "quickIngestInput"],
+  "properties": {
+    "schemaVersion": { "type": "integer", "const": 2 },
+    "draft": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["tools"],
+      "properties": {
+        "tools": {
+          "$ref": "https://agentskeptic.com/schemas/tools-registry.schema.json"
+        }
+      }
+    },
+    "assumptions": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "warnings": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "disclaimer": { "type": "string", "minLength": 1 },
+    "model": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["provider", "model"],
+      "properties": {
+        "provider": { "type": "string", "const": "openai" },
+        "model": { "type": "string", "minLength": 1 }
+      }
+    },
+    "quickIngestInput": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["encoding", "body"],
+      "properties": {
+        "encoding": { "type": "string", "const": "utf8" },
+        "body": {
+          "type": "string",
+          "maxLength": 65536,
+          "description": "NDJSON in quick ingest form; same cap tier as HTTP request body for registry-draft."
+        }
+      }
+    }
+  }
+}

package/schemas/regression-artifact-v1.schema.json

@@ -0,0 +1,212 @@
+{
+  "$id": "https://agentskeptic.com/schemas/regression-artifact-v1.schema.json",
+  "title": "RegressionArtifactV1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "artifactSource",
+    "manifestSha256",
+    "workflowId",
+    "certificateProfile",
+    "verification",
+    "outcomeCertificates",
+    "tracePairwise",
+    "narrative",
+    "humanText",
+    "narrativeHtml"
+  ],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "artifactSource": { "type": "string", "enum": ["cli_manifest", "debug_corpus"] },
+    "manifestSha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+    "workflowId": { "type": "string", "minLength": 1 },
+    "certificateProfile": {
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["mode", "outcomeCertificateRunKind"],
+          "properties": {
+            "mode": { "const": "uniform" },
+            "outcomeCertificateRunKind": {
+              "type": "string",
+              "enum": ["contract_sql", "contract_sql_langgraph_checkpoint_trust"]
+            }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["mode", "entries"],
+          "properties": {
+            "mode": { "const": "perRun" },
+            "entries": {
+              "type": "array",
+              "minItems": 1,
+              "items": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": ["runIndex", "outcomeCertificateRunKind"],
+                "properties": {
+                  "runIndex": { "type": "integer", "minimum": 0 },
+                  "outcomeCertificateRunKind": {
+                    "type": "string",
+                    "enum": ["contract_sql", "contract_sql_langgraph_checkpoint_trust"]
+                  }
+                }
+              }
+            }
+          }
+        }
+      ]
+    },
+    "verification": { "$ref": "https://agentskeptic.com/schemas/run-comparison-report.schema.json" },
+    "outcomeCertificates": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "runIndex",
+          "displayLabel",
+          "outcomeCertificateRunKind",
+          "certificateCanonicalDigest",
+          "certificate"
+        ],
+        "properties": {
+          "runIndex": { "type": "integer", "minimum": 0 },
+          "displayLabel": { "type": "string", "minLength": 1 },
+          "outcomeCertificateRunKind": {
+            "type": "string",
+            "enum": ["contract_sql", "contract_sql_langgraph_checkpoint_trust"]
+          },
+          "certificateCanonicalDigest": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+          "certificate": { "$ref": "https://agentskeptic.com/schemas/outcome-certificate-v1.schema.json" }
+        }
+      }
+    },
+    "tracePairwise": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "priorRunIndex",
+        "currentRunIndex",
+        "viewBuild",
+        "bySeq",
+        "seqTimelineOrderDiverged",
+        "nonToolEventCounts"
+      ],
+      "properties": {
+        "priorRunIndex": { "type": "integer", "minimum": 0 },
+        "currentRunIndex": { "type": "integer", "minimum": 0 },
+        "viewBuild": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["prior", "current"],
+          "properties": {
+            "prior": { "$ref": "https://agentskeptic.com/schemas/execution-trace-view.schema.json" },
+            "current": { "$ref": "https://agentskeptic.com/schemas/execution-trace-view.schema.json" }
+          }
+        },
+        "bySeq": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["seq", "class", "prior", "current"],
+            "properties": {
+              "seq": { "type": "integer", "minimum": 0 },
+              "class": { "type": "string", "enum": ["only_in_prior", "only_in_current", "in_both"] },
+              "prior": { "oneOf": [{ "type": "null" }, { "$ref": "#/$defs/evaluatedNodeSummary" }] },
+              "current": { "oneOf": [{ "type": "null" }, { "$ref": "#/$defs/evaluatedNodeSummary" }] }
+            }
+          }
+        },
+        "seqTimelineOrderDiverged": { "type": "boolean" },
+        "nonToolEventCounts": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["prior", "current"],
+          "properties": {
+            "prior": { "type": "object", "additionalProperties": { "type": "integer", "minimum": 0 } },
+            "current": { "type": "object", "additionalProperties": { "type": "integer", "minimum": 0 } }
+          }
+        }
+      }
+    },
+    "narrative": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "classification",
+        "whyItMatters",
+        "headline",
+        "structural",
+        "traceSummary"
+      ],
+      "properties": {
+        "classification": {
+          "type": "string",
+          "enum": ["improving", "worsening", "unchanged", "mixed"]
+        },
+        "whyItMatters": { "type": "string" },
+        "headline": { "type": "string" },
+        "structural": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "introducedLogicalStepKeysCount",
+            "resolvedLogicalStepKeysCount",
+            "recurringSignatureCount"
+          ],
+          "properties": {
+            "introducedLogicalStepKeysCount": { "type": "integer", "minimum": 0 },
+            "resolvedLogicalStepKeysCount": { "type": "integer", "minimum": 0 },
+            "recurringSignatureCount": { "type": "integer", "minimum": 0 }
+          }
+        },
+        "traceSummary": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "seqTimelineOrderDiverged",
+            "onlyInPriorSeqCount",
+            "onlyInCurrentSeqCount",
+            "inBothCount",
+            "nonToolCountsDiverged"
+          ],
+          "properties": {
+            "seqTimelineOrderDiverged": { "type": "boolean" },
+            "onlyInPriorSeqCount": { "type": "integer", "minimum": 0 },
+            "onlyInCurrentSeqCount": { "type": "integer", "minimum": 0 },
+            "inBothCount": { "type": "integer", "minimum": 0 },
+            "nonToolCountsDiverged": { "type": "boolean" }
+          }
+        }
+      }
+    },
+    "humanText": { "type": "string" },
+    "narrativeHtml": { "type": "string", "minLength": 1 }
+  },
+  "$defs": {
+    "evaluatedNodeSummary": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "ingestIndex",
+        "traceStepKind",
+        "engineStepStatus",
+        "truthOutcomeLabel",
+        "toolId"
+      ],
+      "properties": {
+        "ingestIndex": { "type": "integer", "minimum": 0 },
+        "traceStepKind": { "type": "string" },
+        "engineStepStatus": { "oneOf": [{ "type": "string" }, { "type": "null" }] },
+        "truthOutcomeLabel": { "oneOf": [{ "type": "string" }, { "type": "null" }] },
+        "toolId": { "oneOf": [{ "type": "string" }, { "type": "null" }] }
+      }
+    }
+  }
+}

package/scripts/discovery-payload.lib.cjs

@@ -143,8 +143,10 @@ function buildDiscoveryPayload(root) {
   const { owner, repo } = parseGithubRepoFromUrl(anchors.gitRepositoryUrl);
   const llmsRaw = `https://raw.githubusercontent.com/${owner}/${repo}/refs/heads/${DISCOVERY_LLM_BRANCH}/llms.txt`;
   const llmsBlob = `https://github.com/${owner}/${repo}/blob/${DISCOVERY_LLM_BRANCH}/llms.txt`;
-  const integratorVerificationSsotRaw = `https://raw.githubusercontent.com/${owner}/${repo}/refs/heads/${DISCOVERY_LLM_BRANCH}/docs/integrator-verification.md`;
+  const integratorGuideSsotRaw = `https://raw.githubusercontent.com/${owner}/${repo}/refs/heads/${DISCOVERY_LLM_BRANCH}/docs/integrate.md`;
   const openapiRaw = `https://raw.githubusercontent.com/${owner}/${repo}/refs/heads/${DISCOVERY_LLM_BRANCH}/schemas/openapi-commercial-v1.yaml`;
+  const contractManifestCanonical = `${canonicalOrigin}/contract/v1.json`;
+  const contractManifestRaw = `https://raw.githubusercontent.com/${owner}/${repo}/refs/heads/${DISCOVERY_LLM_BRANCH}/schemas/contract/v1.json`;
   const llms = /** @type {{ intentPhrases: string[]; notFor: string[]; relatedQueries: string[] }} */ (
     discovery.llms
   );
@@ -163,7 +165,9 @@ function buildDiscoveryPayload(root) {
       npm: String(anchors.npmPackageUrl),
       llmsRaw,
       llmsBlob,
-      integratorVerificationSsotRaw,
+      integratorGuideSsotRaw,
+      contractManifestCanonical,
+      contractManifestRaw,
     },
     appendix: {
       slug: String(discovery.slug),
@@ -247,7 +251,7 @@ function renderLlmsTextFromPayload(payload) {
     "",
     "## Primary links",
     `- Canonical site: ${links.site}`,
-    `- Integrator verification SSOT (Python + LangGraph tables): ${links.integratorVerificationSsotRaw}`,
+    `- Integrator guide (v2 SSOT): ${links.integratorGuideSsotRaw}`,
     `- First-run integration: ${integrateUrl}`,
     `- Learn: ${learnHubUrl}`,
     `- OpenAPI (canonical): ${openapiSelfCanonical}`,
@@ -255,6 +259,8 @@ function renderLlmsTextFromPayload(payload) {
     `- Source repository: ${links.repo}`,
     `- npm package: ${links.npm}`,
     `- llms.txt (repo raw): ${links.llmsRaw}`,
+    `- Verification Contract Manifest (canonical): ${links.contractManifestCanonical}`,
+    `- Verification Contract Manifest (repo raw): ${links.contractManifestRaw}`,
     "",
   ];
   const base = lines.join("\n");

package/scripts/emit-primary-marketing.cjs

@@ -29,8 +29,23 @@ const TOKENS = [
   "__DISTRIBUTION_NPM_URL__",
   "__OPENAPI_SELF_URL__",
   "__SERVERS_ORIGIN__",
+  "__CONTRACT_URL__",
+  "__CONTRACT_VERSION__",
+  "__CONTRACT_SHA__",
 ];
 
+const CONTRACT_MANIFEST_PATH = join(ROOT, "schemas", "contract", "v1.json");
+
+function loadContractManifestPin() {
+  const m = JSON.parse(readFileSync(CONTRACT_MANIFEST_PATH, "utf8"));
+  const head = m.history[m.history.length - 1];
+  return {
+    url: String(m.publicUrl),
+    version: String(head.manifestVersion),
+    manifestSha256: String(head.manifestSha256),
+  };
+}
+
 /**
  * @param {string} haystack
  * @param {string} needle
@@ -47,6 +62,8 @@ function countOccurrences(haystack, needle) {
   return n;
 }
 
+const PRODUCT_VERSION_TOKEN = "__PRODUCT_VERSION__";
+
 function validateOpenapiTemplate() {
   const template = readFileSync(OPENAPI_IN, "utf8");
   for (const tok of TOKENS) {
@@ -55,6 +72,10 @@ function validateOpenapiTemplate() {
       throw new Error(`openapi template: token ${tok} must appear exactly once, found ${c}`);
     }
   }
+  const vTok = countOccurrences(template, PRODUCT_VERSION_TOKEN);
+  if (vTok !== 1) {
+    throw new Error(`openapi template: token ${PRODUCT_VERSION_TOKEN} must appear exactly once, found ${vTok}`);
+  }
 }
 
 function escapeYamlDoubleQuotedOneLiner(s) {
@@ -142,6 +163,8 @@ function writeAgentsMd(anchors, discovery) {
   const branch = dp.DISCOVERY_LLM_BRANCH;
   const llmsRaw = `https://raw.githubusercontent.com/${owner}/${repo}/refs/heads/${branch}/llms.txt`;
   const openapiRaw = `https://raw.githubusercontent.com/${owner}/${repo}/refs/heads/${branch}/schemas/openapi-commercial-v1.yaml`;
+  const contractRaw = `https://raw.githubusercontent.com/${owner}/${repo}/refs/heads/${branch}/schemas/contract/v1.json`;
+  const contractPin = loadContractManifestPin();
   const body = `# AGENTS
 
 Normative **public distribution** and anchor sync: [\`docs/public-distribution.md\`](docs/public-distribution.md) (same content as ${url}).
@@ -151,6 +174,8 @@ Normative **public distribution** and anchor sync: [\`docs/public-distribution.m
 - Committed \`llms.txt\` at repo root (same bytes as site \`/llms.txt\` after prebuild sync).
 - Raw GitHub \`llms.txt\`: ${llmsRaw}
 - OpenAPI YAML (repo raw): ${openapiRaw}
+- Verification Contract Manifest (canonical): ${contractPin.url}
+- Verification Contract Manifest (repo raw): ${contractRaw}
 - Acquisition page (canonical): ${acquisitionUrl}
 `;
   writeFileSync(join(ROOT, "AGENTS.md"), body, "utf8");
@@ -178,12 +203,23 @@ function syncPrimaryMarketing() {
   const integrateUrl = `${canonicalOrigin}/integrate`;
 
   const template = readFileSync(OPENAPI_IN, "utf8");
+  const pkgForVersion = JSON.parse(readFileSync(PKG_PATH, "utf8"));
+  const productSemver = String(pkgForVersion.version ?? "").trim();
+  if (!productSemver) {
+    throw new Error("emit-primary-marketing: package.json missing version (OpenAPI __PRODUCT_VERSION__)");
+  }
+  const contractPin = loadContractManifestPin();
+
   let mid = template;
+  mid = mid.replace(PRODUCT_VERSION_TOKEN, JSON.stringify(productSemver));
   mid = mid.replace("__IDENTITY_ONE_LINER__", escaped);
   mid = mid.replace("__DISTRIBUTION_CONTACT_URL__", canonicalOrigin);
   mid = mid.replace("__DISTRIBUTION_INTEGRATE_URL__", integrateUrl);
   mid = mid.replace("__DISTRIBUTION_REPO_URL__", anchors.gitRepositoryUrl);
   mid = mid.replace("__DISTRIBUTION_NPM_URL__", anchors.npmPackageUrl);
+  mid = mid.replace("__CONTRACT_URL__", contractPin.url);
+  mid = mid.replace("__CONTRACT_VERSION__", JSON.stringify(contractPin.version));
+  mid = mid.replace("__CONTRACT_SHA__", JSON.stringify(contractPin.manifestSha256));
 
   const repoYaml = mid
     .replace("__SERVERS_ORIGIN__", canonicalOrigin)
@@ -252,6 +288,7 @@ function syncPrimaryMarketing() {
     `- **Canonical site:** ${canonicalOrigin}`,
     `- **Integrate:** ${integrateUrl}`,
     `- **OpenAPI (canonical):** ${openapiSelfCanonical}`,
+    `- **Verification Contract Manifest:** ${contractPin.url}`,
     `- **llms.txt (agents, site):** ${canonicalOrigin}/llms.txt`,
     `- **llms.txt (repo, raw):** ${pl.llmsRaw}`,
     `- **llms.txt (repo, blob):** ${pl.llmsBlob}`,