@synapsor/runner 1.4.122 → 1.4.123

package/CHANGELOG.md

@@ -1,6 +1,22 @@
 # Changelog
 
-## 1.4.122 (prepared, not published)
+## 1.4.123 (prepared, not published)
+
+### Advisory capability-surface fitness lint
+
+- Adds deterministic `contract lint` advisories for generic query-like string
+  arguments, more than eight capabilities on one normalized target,
+  non-business-operation names, and structurally near-duplicate capabilities.
+- Keeps canonical validation, compilation, MCP serving, and runtime enforcement
+  unchanged. Advisories succeed by default; explicit `--strict` or
+  `--fail-on warning` remains the opt-in CI policy gate.
+- Adds stable structured details and surface metrics to JSON/SARIF output, plus
+  a concise text summary. No database connection, environment value, source
+  row, or probabilistic classifier is involved.
+- Stages only `@synapsor/runner@1.4.123`; `@synapsor/spec@1.4.2`,
+  `@synapsor/dsl@1.4.3`, and `@synapsor/cli@0.1.0-beta.1` are unchanged.
+
+## 1.4.122 (2026-07-16)
 
 ### Trusted principal row scope and Cloud-linked governance
 
@@ -23,8 +39,8 @@
   Runner-token fallback.
 - Introduces the separately packable `@synapsor/cli@0.1.0-beta.1` Cloud client;
   `synapsor-runner` remains the local MCP/database enforcement boundary.
-- Stages `@synapsor/spec@1.4.2`, `@synapsor/dsl@1.4.3`, and
-  `@synapsor/runner@1.4.122`. Nothing is published by this change.
+- Published `@synapsor/spec@1.4.2`, `@synapsor/dsl@1.4.3`, and
+  `@synapsor/runner@1.4.122`.
 
 ## 1.4.121 (prepared, not published)
 

package/README.md

@@ -166,8 +166,8 @@ compensation.
 ## Review And Prove Your Contract
 
 Before serving a contract, use `contract explain` for a reviewer-readable
-boundary, `contract lint --strict` for deterministic CI checks, and `contract
-test` for adopter-owned allow/deny/redaction cases. The built-in language
+boundary, `contract lint --strict` for deterministic surface-fitness CI checks,
+and `contract test` for adopter-owned allow/deny/redaction cases. The built-in language
 server supplies diagnostics, completion, hover, and formatting for
 `.synapsor.sql` and legacy `.synapsor` files. See [Contract
 Review](docs/contract-review.md) and [Contract

package/dist/runner.mjs

@@ -41376,6 +41376,299 @@ function isRecord7(value) {
 // apps/runner/src/contract-tools.ts
 import fs5 from "node:fs/promises";
 import path5 from "node:path";
+
+// apps/runner/src/capability-surface-lint.ts
+var CAPABILITY_SURFACE_DENSITY_REVIEW_THRESHOLD = 8;
+var GENERIC_ARGUMENT_NAMES = /* @__PURE__ */ new Set(["filter", "predicate", "query", "sql", "where"]);
+var ACTION_PREFIXES = /* @__PURE__ */ new Set([
+  "add",
+  "answer",
+  "archive",
+  "assign",
+  "cancel",
+  "change",
+  "close",
+  "count",
+  "create",
+  "delete",
+  "export",
+  "find",
+  "get",
+  "grant",
+  "inspect",
+  "list",
+  "lookup",
+  "open",
+  "propose",
+  "read",
+  "refund",
+  "remove",
+  "request",
+  "resolve",
+  "restore",
+  "revert",
+  "search",
+  "set",
+  "sum",
+  "update",
+  "verify",
+  "waive",
+  "write"
+]);
+var ACTION_SUFFIXES = /* @__PURE__ */ new Set(["average", "count", "lookup", "review", "search", "summary", "total"]);
+var GENERIC_OPERATION_WORDS = /* @__PURE__ */ new Set([
+  "create",
+  "data",
+  "database",
+  "db",
+  "delete",
+  "execute",
+  "get",
+  "item",
+  "manage",
+  "mutate",
+  "object",
+  "process",
+  "query",
+  "read",
+  "record",
+  "resource",
+  "row",
+  "run",
+  "set",
+  "sql",
+  "table",
+  "thing",
+  "update",
+  "write"
+]);
+function analyzeCapabilitySurface(contract) {
+  const resources = new Map((contract.resources ?? []).map((resource) => [resource.name, resource]));
+  const indexed = contract.capabilities.map((capability) => {
+    const resource = capability.subject.resource ? resources.get(capability.subject.resource) : void 0;
+    const source = capability.source ?? resource?.engine ?? "unresolved-source";
+    const schema = capability.subject.schema ?? resource?.schema ?? "unresolved-schema";
+    const table = capability.subject.table ?? resource?.table ?? capability.subject.resource ?? "unresolved-object";
+    return {
+      capability,
+      targetKey: `${source}\0${schema}\0${table}`,
+      targetLabel: `${source}:${schema}.${table}`
+    };
+  });
+  const findings = [];
+  for (const entry of indexed) {
+    collectGenericArgumentFindings(findings, entry);
+    collectOperationNamingFinding(findings, entry);
+  }
+  const grouped = /* @__PURE__ */ new Map();
+  for (const entry of indexed) grouped.set(entry.targetKey, [...grouped.get(entry.targetKey) ?? [], entry]);
+  const targets = [...grouped.values()].map((entries) => {
+    const sortedEntries = [...entries].sort((left, right) => left.capability.name.localeCompare(right.capability.name));
+    const capabilityNames = sortedEntries.map((entry) => entry.capability.name);
+    const densityWarning = entries.length > CAPABILITY_SURFACE_DENSITY_REVIEW_THRESHOLD;
+    if (densityWarning) {
+      findings.push({
+        code: "SURFACE_TARGET_DENSITY",
+        severity: "warning",
+        path: "$.capabilities",
+        message: `${entries[0].targetLabel} exposes ${entries.length} capabilities, above the advisory review threshold of ${CAPABILITY_SURFACE_DENSITY_REVIEW_THRESHOLD}. Review whether every operation belongs on the same model-facing surface or should be consolidated or assigned to a narrower agent.`,
+        details: {
+          target: entries[0].targetLabel,
+          capability_count: entries.length,
+          review_threshold: CAPABILITY_SURFACE_DENSITY_REVIEW_THRESHOLD,
+          capabilities: capabilityNames
+        }
+      });
+    }
+    collectNearDuplicateFindings(findings, sortedEntries);
+    return {
+      target: entries[0].targetLabel,
+      capability_count: entries.length,
+      capabilities: capabilityNames,
+      density_warning: densityWarning
+    };
+  }).sort((left, right) => left.target.localeCompare(right.target));
+  findings.sort((left, right) => left.code.localeCompare(right.code) || left.path.localeCompare(right.path) || left.message.localeCompare(right.message));
+  return {
+    findings,
+    summary: {
+      total_capabilities: indexed.length,
+      target_count: targets.length,
+      density_review_threshold: CAPABILITY_SURFACE_DENSITY_REVIEW_THRESHOLD,
+      targets
+    }
+  };
+}
+function collectGenericArgumentFindings(findings, entry) {
+  const visit = (arg, argName, argPath) => {
+    if (arg.type === "object_array") {
+      for (const [fieldName, field] of Object.entries(arg.fields).sort(([left], [right]) => left.localeCompare(right))) {
+        visit(field, fieldName, `${argPath}.fields.${fieldName}`);
+      }
+      return;
+    }
+    const normalizedName = normalizeIdentifier(argName);
+    if (arg.type !== "string" || (arg.enum?.length ?? 0) > 0 || !GENERIC_ARGUMENT_NAMES.has(normalizedName)) return;
+    findings.push({
+      code: "SURFACE_GENERIC_ARGUMENT",
+      severity: "warning",
+      path: argPath,
+      message: `${entry.capability.name} exposes un-enumerated string argument ${argName}, a generic query/predicate-style name. Runner does not turn it into SQL, but reviewers should confirm this remains a named business operation instead of an escape-hatch surface.`,
+      details: { capability: entry.capability.name, argument: argName }
+    });
+  };
+  for (const [argName, arg] of Object.entries(entry.capability.args).sort(([left], [right]) => left.localeCompare(right))) {
+    visit(arg, argName, `${capabilityPath(entry.capability.name)}.args.${argName}`);
+  }
+}
+function collectOperationNamingFinding(findings, entry) {
+  const operation = entry.capability.name.split(".").at(-1) ?? entry.capability.name;
+  const tokens = tokenizeIdentifier(operation);
+  const genericOnly = tokens.length > 0 && tokens.every((token) => GENERIC_OPERATION_WORDS.has(token));
+  const actionOriented = tokens.length >= 2 && (ACTION_PREFIXES.has(tokens[0]) || ACTION_SUFFIXES.has(tokens.at(-1)));
+  if (tokens.length >= 2 && actionOriented && !genericOnly) return;
+  findings.push({
+    code: "SURFACE_OPERATION_NAMING",
+    severity: "warning",
+    path: `${capabilityPath(entry.capability.name)}.name`,
+    message: `${entry.capability.name} does not read as a high-confidence named business operation. Use a reviewer-recognizable operation such as inspect_invoice or propose_plan_credit; this is a naming heuristic, not a runtime enforcement failure.`,
+    details: { capability: entry.capability.name, operation, tokens }
+  });
+}
+function collectNearDuplicateFindings(findings, entries) {
+  for (let leftIndex = 0; leftIndex < entries.length; leftIndex += 1) {
+    for (let rightIndex = leftIndex + 1; rightIndex < entries.length; rightIndex += 1) {
+      const left = entries[leftIndex];
+      const right = entries[rightIndex];
+      if (left.capability.kind !== right.capability.kind || capabilityShape(left.capability) !== capabilityShape(right.capability)) continue;
+      const relationship = compareArgumentSurfaces(left.capability.args, right.capability.args);
+      if (!relationship) continue;
+      const differences = relationship.differences.length > 0 ? relationship.differences : ["identical model-visible arguments"];
+      findings.push({
+        code: "SURFACE_NEAR_DUPLICATE",
+        severity: "warning",
+        path: "$.capabilities",
+        message: `${left.capability.name} and ${right.capability.name} have the same target, kind, reviewed fields, targeting, and write/approval shape, with only this argument-surface difference: ${differences.join("; ")}. Review whether both operations are necessary or one is a loosened duplicate.`,
+        details: {
+          target: left.targetLabel,
+          capabilities: [left.capability.name, right.capability.name],
+          relationship: relationship.relationship,
+          differences
+        }
+      });
+    }
+  }
+}
+function capabilityShape(capability) {
+  const { name: _name, description: _description, returns_hint: _returnsHint, args: _args, ...shape } = capability;
+  return stableString(shape);
+}
+function compareArgumentSurfaces(left, right) {
+  if (stableString(stripArgumentDescriptions(left)) === stableString(stripArgumentDescriptions(right))) {
+    return { relationship: "identical", differences: [] };
+  }
+  const leftLooser = argumentMapNoStricter(left, right);
+  const rightLooser = argumentMapNoStricter(right, left);
+  if (leftLooser && !rightLooser) return { relationship: "left_is_looser", differences: describeRelaxations(left, right) };
+  if (rightLooser && !leftLooser) return { relationship: "right_is_looser", differences: describeRelaxations(right, left) };
+  return void 0;
+}
+function argumentMapNoStricter(looser, stricter) {
+  for (const [name, strictArg] of Object.entries(stricter)) {
+    const looseArg = looser[name];
+    if (!looseArg || !argumentNoStricter(looseArg, strictArg)) return false;
+  }
+  return Object.entries(looser).filter(([name]) => !(name in stricter)).every(([, arg]) => arg.required !== true);
+}
+function argumentNoStricter(looser, stricter) {
+  if (looser.type !== stricter.type) return false;
+  if (looser.required === true && stricter.required !== true) return false;
+  if (looser.type === "object_array" && stricter.type === "object_array") {
+    if (!sameExtensions(looser, stricter)) return false;
+    if (looser.max_items < stricter.max_items) return false;
+    return argumentMapNoStricter(looser.fields, stricter.fields);
+  }
+  if (looser.type === "object_array" || stricter.type === "object_array") return false;
+  if (!sameExtensions(looser, stricter)) return false;
+  if ((looser.max_length ?? Number.POSITIVE_INFINITY) < (stricter.max_length ?? Number.POSITIVE_INFINITY)) return false;
+  if ((looser.minimum ?? Number.NEGATIVE_INFINITY) > (stricter.minimum ?? Number.NEGATIVE_INFINITY)) return false;
+  if ((looser.maximum ?? Number.POSITIVE_INFINITY) < (stricter.maximum ?? Number.POSITIVE_INFINITY)) return false;
+  return enumContains(looser.enum, stricter.enum);
+}
+function enumContains(looser, stricter) {
+  if (!looser?.length) return true;
+  if (!stricter?.length) return false;
+  const looseValues = new Set(looser.map((value) => stableString(value)));
+  return stricter.every((value) => looseValues.has(stableString(value)));
+}
+function describeRelaxations(looser, stricter) {
+  const differences = [];
+  for (const name of Object.keys(looser).sort()) {
+    const looseArg = looser[name];
+    const strictArg = stricter[name];
+    if (!strictArg) {
+      differences.push(`${name} adds an optional argument`);
+      continue;
+    }
+    describeArgumentRelaxations(looseArg, strictArg, name, differences);
+  }
+  return differences;
+}
+function describeArgumentRelaxations(looser, stricter, path9, differences) {
+  if (looser.required !== true && stricter.required === true) differences.push(`${path9} becomes optional`);
+  if (looser.type === "object_array" && stricter.type === "object_array") {
+    if (looser.max_items > stricter.max_items) differences.push(`${path9}.max_items increases from ${stricter.max_items} to ${looser.max_items}`);
+    for (const name of Object.keys(looser.fields).sort()) {
+      const looseField = looser.fields[name];
+      const strictField = stricter.fields[name];
+      if (!strictField) differences.push(`${path9}.${name} adds an optional field`);
+      else describeArgumentRelaxations(looseField, strictField, `${path9}.${name}`, differences);
+    }
+    return;
+  }
+  if (looser.type === "object_array" || stricter.type === "object_array") return;
+  if ((looser.max_length ?? Number.POSITIVE_INFINITY) > (stricter.max_length ?? Number.POSITIVE_INFINITY)) differences.push(`${path9}.max_length widens from ${displayBound(stricter.max_length)} to ${displayBound(looser.max_length)}`);
+  if ((looser.minimum ?? Number.NEGATIVE_INFINITY) < (stricter.minimum ?? Number.NEGATIVE_INFINITY)) differences.push(`${path9}.minimum widens from ${displayBound(stricter.minimum)} to ${displayBound(looser.minimum)}`);
+  if ((looser.maximum ?? Number.POSITIVE_INFINITY) > (stricter.maximum ?? Number.POSITIVE_INFINITY)) differences.push(`${path9}.maximum widens from ${displayBound(stricter.maximum)} to ${displayBound(looser.maximum)}`);
+  if (stableString(looser.enum ?? []) !== stableString(stricter.enum ?? [])) differences.push(`${path9}.enum widens from ${displayEnum(stricter.enum)} to ${displayEnum(looser.enum)}`);
+}
+function stripArgumentDescriptions(args) {
+  return Object.fromEntries(Object.entries(args).map(([name, arg]) => [name, stripArgumentDescription(arg)]));
+}
+function stripArgumentDescription(arg) {
+  const { description: _description, ...rest } = arg;
+  if (arg.type !== "object_array") return rest;
+  return { ...rest, fields: Object.fromEntries(Object.entries(arg.fields).map(([name, field]) => [name, stripArgumentDescription(field)])) };
+}
+function sameExtensions(left, right) {
+  const extensionEntries = (value) => Object.fromEntries(Object.entries(value).filter(([key]) => key.startsWith("x-")));
+  return stableString(extensionEntries(left)) === stableString(extensionEntries(right));
+}
+function normalizeIdentifier(value) {
+  return tokenizeIdentifier(value).join("_");
+}
+function capabilityPath(name) {
+  return `$.capabilities[name=${JSON.stringify(name)}]`;
+}
+function tokenizeIdentifier(value) {
+  return value.replace(/([a-z0-9])([A-Z])/g, "$1_$2").toLowerCase().split(/[^a-z0-9]+/).filter(Boolean);
+}
+function stableString(value) {
+  return JSON.stringify(stableValue(value));
+}
+function stableValue(value) {
+  if (Array.isArray(value)) return value.map(stableValue).sort((left, right) => JSON.stringify(left).localeCompare(JSON.stringify(right)));
+  if (!value || typeof value !== "object") return value;
+  return Object.fromEntries(Object.entries(value).filter(([, nested]) => nested !== void 0).sort(([left], [right]) => left.localeCompare(right)).map(([key, nested]) => [key, stableValue(nested)]));
+}
+function displayBound(value) {
+  return value === void 0 ? "unbounded" : String(value);
+}
+function displayEnum(value) {
+  return value?.length ? JSON.stringify([...value].map(stableValue).sort()) : "any value";
+}
+
+// apps/runner/src/contract-tools.ts
 async function loadReviewedContract(sourcePath) {
   const absolute = path5.resolve(sourcePath);
   const sourceText = await fs5.readFile(absolute, "utf8");
@@ -41478,13 +41771,15 @@ function lintContract(contract, options = {}) {
       add({ code: "IRREVERSIBLE_DELETE_REVIEW", severity: "warning", path: `${base}.proposal.reversibility`, message: `${capability.name} performs a hard delete without reviewed inverse compensation.` });
     }
   }
+  const surface = analyzeCapabilitySurface(contract);
+  for (const finding of surface.findings) add(finding);
   issues.sort((left, right) => severityRank(left.severity) - severityRank(right.severity) || left.code.localeCompare(right.code) || left.path.localeCompare(right.path));
   const summary = {
     errors: issues.filter((issue) => issue.severity === "error").length,
     warnings: issues.filter((issue) => issue.severity === "warning").length,
     info: issues.filter((issue) => issue.severity === "info").length
   };
-  return { ok: summary.errors === 0, issues, summary };
+  return { ok: summary.errors === 0, issues, summary, surface: surface.summary };
 }
 function formatContractLint(result, format) {
   if (format === "json") return `${JSON.stringify(result, null, 2)}
@@ -41499,13 +41794,16 @@ function formatContractLint(result, format) {
           ruleId: issue.code,
           level: issue.severity === "error" ? "error" : issue.severity === "warning" ? "warning" : "note",
           message: { text: issue.message },
-          locations: [{ physicalLocation: { artifactLocation: { uri: issue.path } } }]
+          locations: [{ physicalLocation: { artifactLocation: { uri: issue.path } } }],
+          ...issue.details ? { properties: issue.details } : {}
         }))
       }]
     }, null, 2)}
 `;
   }
   const lines = result.issues.map((issue) => `${issue.severity.toUpperCase()} ${issue.code} ${issue.path}: ${issue.message}`);
+  const denseTargets = result.surface.targets.filter((target2) => target2.density_warning).length;
+  lines.push(`Surface: ${result.surface.total_capabilities} model-facing capabilities across ${result.surface.target_count} targets; ${denseTargets} target(s) above the advisory density threshold of ${result.surface.density_review_threshold}`);
   lines.push(`Summary: ${result.summary.errors} error / ${result.summary.warnings} warning / ${result.summary.info} info`);
   return `${lines.join("\n")}
 `;
@@ -42753,7 +43051,7 @@ function rate(value) {
 // apps/runner/package.json
 var package_default = {
   name: "@synapsor/runner",
-  version: "1.4.122",
+  version: "1.4.123",
   description: "Stop giving AI agents execute_sql; expose reviewed Postgres/MySQL MCP actions with proposals, approval, writeback, and replay.",
   license: "Apache-2.0",
   type: "module",

package/docs/capability-authoring.md

@@ -121,6 +121,22 @@ synapsor-runner mcp serve --config ./synapsor.runner.json --store ./.synapsor/lo
 capabilities cannot accidentally lose descriptions, returns hints, or numeric
 patch bounds during review.
 
+After compilation, run the canonical contract through the surface review:
+
+```bash
+synapsor-runner contract lint ./synapsor.contract.json
+synapsor-runner contract lint ./synapsor.contract.json --strict
+```
+
+The default command keeps capability-surface findings advisory; `--strict` opts
+into warning-as-failure CI policy. Review capabilities using a simple fitness
+test: if the name is not a business operation an audit log would recognize, ask
+whether the model should receive it. Lint also surfaces generic query-like
+string arguments, more than eight capabilities on one target, and structurally
+near-duplicate tools. These checks make breadth drift visible; they do not
+change canonical validity or replace human review. See [Contract
+Review](contract-review.md) for exact codes and behavior.
+
 ## DSL / JSON Capability Parity
 
 The DSL compiles to canonical `@synapsor/spec` JSON. It must not silently weaken

package/docs/contract-review.md

@@ -33,9 +33,42 @@ cover objective review gaps such as missing descriptions/evidence, unbounded
 strings, unresolved wiring, irreversible operations, and policy/writeback
 contradictions. Lint does not claim to discover every sensitive column.
 
+### Review Capability-Surface Fitness
+
+Runner structurally limits capability **depth**: contracts cannot turn a model
+argument into raw SQL or a free-form predicate, and trusted tenant/principal
+scope is never model input. A separate review concern is capability **breadth**:
+many individually narrow tools can accumulate until the total model-facing
+surface is difficult to understand.
+
+Use this fitness test during review:
+
+> If a capability cannot be described as a named business operation an audit
+> log would recognize, it probably should not be exposed yet.
+
+`contract lint` reports these deterministic advisory warnings:
+
+| Code | Review signal |
+| --- | --- |
+| `SURFACE_GENERIC_ARGUMENT` | An un-enumerated string argument is literally named `filter`, `query`, `where`, `predicate`, or `sql`. Runner still does not interpolate it into SQL. |
+| `SURFACE_TARGET_DENSITY` | More than eight capabilities target the same normalized source and object. Eight is a review threshold, not a runtime limit. |
+| `SURFACE_OPERATION_NAMING` | A capability name does not match the conservative named-business-operation heuristic. |
+| `SURFACE_NEAR_DUPLICATE` | Two capabilities have the same target, kind, reviewed fields, targeting, write/approval shape, and identical or directionally loosened arguments. |
+
+The default command exits successfully when these advisories are the only
+findings. `--strict` (or `--fail-on warning`) deliberately lets a team turn all
+warnings into a CI policy gate without changing canonical contract validity.
+Text, JSON, and SARIF use the same stable finding set and deterministic order.
+
+Passing these checks does not prove that a surface is safe or well designed.
+Review which operations each agent actually needs; use narrower contracts or
+Runner/client deployments instead of exposing every organization capability to
+every model.
+
 Expected successful output ends with:
 
 ```text
+Surface: N model-facing capabilities across M targets; 0 target(s) above the advisory density threshold of 8
 Summary: 0 error / 0 warning / N info
 ```
 

package/docs/release-notes.md

@@ -10,7 +10,25 @@ npx -y -p @synapsor/runner synapsor-runner demo --quick
 The OSS runner command is `synapsor-runner`. The `synapsor` command is reserved
 for the Synapsor Cloud CLI.
 
-## 1.4.122 (prepared, not published)
+## 1.4.123 (prepared, not published)
+
+### Advisory capability-surface fitness lint
+
+- `contract lint` now reports high-signal breadth-drift advisories for generic
+  query/predicate-style string arguments, capability density above eight on one
+  target, operation names that do not read as business actions, and structural
+  near-duplicates with identical or loosened arguments.
+- Findings are deterministic across declaration order and share stable codes in
+  text, JSON, and SARIF. JSON/SARIF include reviewer-safe metrics and structural
+  differences without reading a database or environment values.
+- Advisory-only lint still exits successfully by default. Teams may opt into a
+  CI policy gate with `--strict` or `--fail-on warning`; canonical validity and
+  runtime enforcement are unchanged.
+
+Prepared package version: `@synapsor/runner@1.4.123`. Spec, DSL, and Cloud CLI
+packages are unchanged.
+
+## 1.4.122 (2026-07-16)
 
 ### Trusted principal scope and Cloud-linked authority
 

package/docs/security-boundary.md

@@ -142,7 +142,10 @@ credentials, approval tools, commit tools, or controls that widen reviewed
 tables/columns.
 
 Contract lint and tests are review aids rather than a proof of complete
-security. Scoped report exports omit evidence rows and kept-out values and are
+security. Capability breadth can still drift as narrow tools accumulate;
+surface-fitness lint makes high-signal generic, dense, poorly named, and
+near-duplicate surfaces visible for review but does not enforce good design.
+Scoped report exports omit evidence rows and kept-out values and are
 tamper-evident when their digest/signature verifies; local SQLite is not an
 immutable compliance service. Graduated-trust evaluation is operator-only,
 disabled by default, and can recommend/export a separate artifact but cannot

package/fixtures/contracts/capability-surface-fitness.contract.json

@@ -0,0 +1,190 @@
+{
+  "spec_version": "0.1",
+  "kind": "SynapsorContract",
+  "metadata": {
+    "name": "capability surface fitness fixture",
+    "description": "Exercises advisory capability-breadth review without changing contract validity.",
+    "version": "1.0.0"
+  },
+  "resources": [
+    {
+      "name": "billing_invoices",
+      "engine": "postgres",
+      "schema": "public",
+      "table": "invoices",
+      "type": "table",
+      "primary_key": "id",
+      "tenant_key": "tenant_id",
+      "conflict_key": "updated_at"
+    }
+  ],
+  "contexts": [
+    {
+      "name": "billing_operator",
+      "bindings": [
+        {
+          "name": "tenant_id",
+          "source": "environment",
+          "key": "SYNAPSOR_TENANT_ID",
+          "required": true
+        }
+      ],
+      "tenant_binding": "tenant_id"
+    }
+  ],
+  "capabilities": [
+    {
+      "name": "billing.execute",
+      "description": "Look up one reviewed invoice reference.",
+      "returns_hint": "One allowlisted invoice row.",
+      "kind": "read",
+      "context": "billing_operator",
+      "source": "local_postgres",
+      "subject": { "resource": "billing_invoices" },
+      "args": {
+        "filter": { "type": "string", "required": true, "max_length": 128 }
+      },
+      "lookup": { "id_from_arg": "filter" },
+      "visible_fields": ["id", "tenant_id", "status"],
+      "kept_out_fields": ["card_token", "internal_note"],
+      "evidence": { "required": true, "query_audit": true },
+      "max_rows": 1
+    },
+    {
+      "name": "billing.inspect_invoice_primary",
+      "description": "Inspect one primary invoice.",
+      "returns_hint": "One allowlisted invoice row.",
+      "kind": "read",
+      "context": "billing_operator",
+      "source": "local_postgres",
+      "subject": { "resource": "billing_invoices" },
+      "args": {
+        "invoice_id": { "type": "string", "required": true, "max_length": 128 }
+      },
+      "lookup": { "id_from_arg": "invoice_id" },
+      "visible_fields": ["id", "tenant_id", "status"],
+      "kept_out_fields": ["card_token", "internal_note"],
+      "evidence": { "required": true, "query_audit": true },
+      "max_rows": 1
+    },
+    {
+      "name": "billing.inspect_invoice_copy",
+      "description": "Inspect the same reviewed invoice shape for duplicate detection.",
+      "returns_hint": "One allowlisted invoice row.",
+      "kind": "read",
+      "context": "billing_operator",
+      "source": "local_postgres",
+      "subject": { "resource": "billing_invoices" },
+      "args": {
+        "invoice_id": { "type": "string", "required": true, "max_length": 128 }
+      },
+      "lookup": { "id_from_arg": "invoice_id" },
+      "visible_fields": ["id", "tenant_id", "status"],
+      "kept_out_fields": ["card_token", "internal_note"],
+      "evidence": { "required": true, "query_audit": true },
+      "max_rows": 1
+    },
+    {
+      "name": "billing.inspect_invoice_secondary",
+      "description": "Inspect one secondary invoice.",
+      "returns_hint": "One allowlisted invoice row.",
+      "kind": "read",
+      "context": "billing_operator",
+      "source": "local_postgres",
+      "subject": { "resource": "billing_invoices" },
+      "args": {
+        "secondary_invoice_id": { "type": "string", "required": true, "max_length": 128 }
+      },
+      "lookup": { "id_from_arg": "secondary_invoice_id" },
+      "visible_fields": ["id", "tenant_id", "status"],
+      "kept_out_fields": ["card_token", "internal_note"],
+      "evidence": { "required": true, "query_audit": true },
+      "max_rows": 1
+    },
+    {
+      "name": "billing.inspect_invoice_archived",
+      "description": "Inspect one archived invoice.",
+      "returns_hint": "One allowlisted invoice row.",
+      "kind": "read",
+      "context": "billing_operator",
+      "source": "local_postgres",
+      "subject": { "resource": "billing_invoices" },
+      "args": {
+        "archived_invoice_id": { "type": "string", "required": true, "max_length": 128 }
+      },
+      "lookup": { "id_from_arg": "archived_invoice_id" },
+      "visible_fields": ["id", "tenant_id", "status"],
+      "kept_out_fields": ["card_token", "internal_note"],
+      "evidence": { "required": true, "query_audit": true },
+      "max_rows": 1
+    },
+    {
+      "name": "billing.inspect_invoice_disputed",
+      "description": "Inspect one disputed invoice.",
+      "returns_hint": "One allowlisted invoice row.",
+      "kind": "read",
+      "context": "billing_operator",
+      "source": "local_postgres",
+      "subject": { "resource": "billing_invoices" },
+      "args": {
+        "disputed_invoice_id": { "type": "string", "required": true, "max_length": 128 }
+      },
+      "lookup": { "id_from_arg": "disputed_invoice_id" },
+      "visible_fields": ["id", "tenant_id", "status"],
+      "kept_out_fields": ["card_token", "internal_note"],
+      "evidence": { "required": true, "query_audit": true },
+      "max_rows": 1
+    },
+    {
+      "name": "billing.inspect_invoice_overdue",
+      "description": "Inspect one overdue invoice.",
+      "returns_hint": "One allowlisted invoice row.",
+      "kind": "read",
+      "context": "billing_operator",
+      "source": "local_postgres",
+      "subject": { "resource": "billing_invoices" },
+      "args": {
+        "overdue_invoice_id": { "type": "string", "required": true, "max_length": 128 }
+      },
+      "lookup": { "id_from_arg": "overdue_invoice_id" },
+      "visible_fields": ["id", "tenant_id", "status"],
+      "kept_out_fields": ["card_token", "internal_note"],
+      "evidence": { "required": true, "query_audit": true },
+      "max_rows": 1
+    },
+    {
+      "name": "billing.inspect_invoice_paid",
+      "description": "Inspect one paid invoice.",
+      "returns_hint": "One allowlisted invoice row.",
+      "kind": "read",
+      "context": "billing_operator",
+      "source": "local_postgres",
+      "subject": { "resource": "billing_invoices" },
+      "args": {
+        "paid_invoice_id": { "type": "string", "required": true, "max_length": 128 }
+      },
+      "lookup": { "id_from_arg": "paid_invoice_id" },
+      "visible_fields": ["id", "tenant_id", "status"],
+      "kept_out_fields": ["card_token", "internal_note"],
+      "evidence": { "required": true, "query_audit": true },
+      "max_rows": 1
+    },
+    {
+      "name": "billing.inspect_invoice_voided",
+      "description": "Inspect one voided invoice.",
+      "returns_hint": "One allowlisted invoice row.",
+      "kind": "read",
+      "context": "billing_operator",
+      "source": "local_postgres",
+      "subject": { "resource": "billing_invoices" },
+      "args": {
+        "voided_invoice_id": { "type": "string", "required": true, "max_length": 128 }
+      },
+      "lookup": { "id_from_arg": "voided_invoice_id" },
+      "visible_fields": ["id", "tenant_id", "status"],
+      "kept_out_fields": ["card_token", "internal_note"],
+      "evidence": { "required": true, "query_audit": true },
+      "max_rows": 1
+    }
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synapsor/runner",
-  "version": "1.4.122",
+  "version": "1.4.123",
   "description": "Stop giving AI agents execute_sql; expose reviewed Postgres/MySQL MCP actions with proposals, approval, writeback, and replay.",
   "license": "Apache-2.0",
   "type": "module",