@tineira/apc-conformance 0.7.0 → 0.7.1

package/dist/http.js

@@ -10,8 +10,8 @@
  * no credentials in URLs, every grant URL on the app's own origin, redirects never followed (a 3xx is a
  * failure), a byte cap on every body and a timeout on every request.
  */
-import { APC_JSON_MAX_BYTES, APC_JSON_PATH, APC_STANDARD_VERSION, CORE_TOOLS, REVOKED_HTTP_STATUS, compareStandard, declaresMcpUrl, isRevokedAnswer, parseApcManifest, } from "@tineira/apc-protocol";
-import { ConformanceError, ISO, attentionOf, checkCoreToolList, checkFocusShape, checkView, data, expect, isObject, resultKey, rpcBody } from "./shared.js";
+import { APC_JSON_MAX_BYTES, APC_JSON_PATH, APC_STANDARD_VERSION, CORE_TOOLS, REVOKED_HTTP_STATUS, declaresMcpUrl, isRevokedAnswer, parseApcManifest, } from "@tineira/apc-protocol";
+import { ConformanceError, ISO, attentionOf, checkCoreToolList, checkFocusShape, checkView, data, expect, isObject, resultKey, rpcBody, standardSupport } from "./shared.js";
 /**
  * The checks of the suite that need the person's page (an adapter in process), not reachable over HTTP:
  * `apcConformance(adapter)` runs them in the app's own tests.
@@ -267,12 +267,15 @@ function build(options) {
         },
         {
             id: "apc-json-standard",
-            name: `its standard is one these checks know (0.5.0 to ${APC_STANDARD_VERSION})`,
+            name: `its standard is one these checks know (0.5.0 to ${APC_STANDARD_VERSION}, or a newer patch of it)`,
             async run() {
                 if (!manifest)
                     return "apc.json did not parse";
-                expect(compareStandard(manifest.standard, "0.5.0") >= 0, `standard is ${manifest.standard}: apc.json exists since 0.5.0`);
-                expect(compareStandard(manifest.standard, APC_STANDARD_VERSION) <= 0, `standard is ${manifest.standard}, newer than the ${APC_STANDARD_VERSION} these checks know: update @tineira/apc-conformance`);
+                const support = standardSupport(manifest.standard, APC_STANDARD_VERSION);
+                if (!support.ok)
+                    throw new ConformanceError(support.reason);
+                if (support.note)
+                    return { note: support.note };
             },
         },
         {

package/dist/index.d.ts

@@ -99,7 +99,10 @@ export interface ApcAppAdapter {
 }
 export interface ConformanceCheck {
     name: string;
+    /** Throws when the check fails. */
     run(): Promise<void>;
+    /** Set by `run()` when the check passed with something worth saying (a newer patch of the standard, say). */
+    note?: string;
 }
 export interface ConformanceReport {
     app: string;
@@ -110,6 +113,7 @@ export interface ConformanceReport {
         name: string;
         ok: boolean;
         error?: string;
+        note?: string;
     }>;
 }
 /** The checks of the core, in order. Each makes its own agents, so any one can run alone. */

package/dist/index.js

@@ -19,9 +19,21 @@
  * and a revoked grant's answer); the `apc-conformance` command (`cli.ts`) runs them from a terminal.
  */
 import { APC_AGENT_CLIENT_META, APC_JSON_MAX_BYTES, APC_JSON_PATH, APC_MOBILE_VIEWPORT, APC_STANDARD_VERSION, APC_LINK_KEY, APC_LINK_TOOL, APC_LINK_TTL_S, CORE_TOOLS, LINK_REFUSED_ERROR, REVOKED_ERROR, REVOKED_HTTP_STATUS, canonicalTarget, compareStandard, declaresMcpUrl, isRevokedAnswer, parseApcManifest, } from "@tineira/apc-protocol";
-import { ConformanceError, ISO, attentionOf, checkCoreToolList, checkFocusShape, checkView, data, expect, isObject, resultKey, rpcBody, text } from "./shared.js";
+import { ConformanceError, ISO, attentionOf, checkCoreToolList, checkFocusShape, checkView, data, expect, isObject, resultKey, rpcBody, standardSupport, text } from "./shared.js";
 export { ConformanceError } from "./shared.js";
 export { HttpConformanceUsageError, IN_PROCESS_ONLY, httpConformance, redactGrantUrl, redactSecrets, runHttpConformance, } from "./http.js";
+/** A check whose body may resolve to `{ note }`: the note lands on the check, and `run()` stays a test body. */
+function noted(name, body) {
+    const check = {
+        name,
+        async run() {
+            const out = await body();
+            if (out?.note)
+                check.note = out.note;
+        },
+    };
+    return check;
+}
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 /** One JSON-RPC request over Streamable HTTP, stateless, as a dock's hub sends it: the HTTP status and the reply. */
 async function send(app, url, method, params) {
@@ -59,7 +71,7 @@ async function timed(work) {
 /** The checks of the core, in order. Each makes its own agents, so any one can run alone. */
 export function apcConformance(app) {
     const [first, second] = app.targets;
-    const check = (name, run) => ({ name: `${app.name} (${app.profile}): ${name}`, run });
+    const check = (name, run) => noted(`${app.name} (${app.profile}): ${name}`, run);
     return [
         check("serves apc.json from its own origin, naming the profiles it serves and where its MCP URLs live", async () => {
             const { mcpUrl } = await app.connect();
@@ -80,7 +92,8 @@ export function apcConformance(app) {
             const parsed = parseApcManifest(body, origin);
             expect(parsed.ok, `${APC_JSON_PATH}: ${parsed.ok ? "" : `${parsed.error}, ${parsed.detail}`}`);
             const m = parsed.manifest;
-            expect(compareStandard(m.standard, "0.5.0") >= 0 && compareStandard(m.standard, APC_STANDARD_VERSION) <= 0, `standard is ${m.standard}: apc.json exists since 0.5.0, and this suite checks up to ${APC_STANDARD_VERSION}`);
+            const support = standardSupport(m.standard, APC_STANDARD_VERSION);
+            expect(support.ok, support.ok ? "" : `${support.reason} (this suite checks 0.5.0 up to ${APC_STANDARD_VERSION}, and newer patches of it)`);
             expect(!m.profiles.includes("hub"), "an app's profiles are direct, dock or both, never hub");
             expect(m.profiles.includes(app.profile), `profiles ${JSON.stringify(m.profiles)} leave out ${app.profile}, which the app serves`);
             if (app.link)
@@ -88,6 +101,8 @@ export function apcConformance(app) {
             expect(declaresMcpUrl(m, mcpUrl), `the grant's MCP URL is not under ${origin}${m.mcp.path} (mcp.path)`);
             if (m.profiles.includes("direct"))
                 expect(m.direct && new URL(m.direct.connect).origin === origin, "direct.connect is the app's own page");
+            if (support.note)
+                return { note: support.note };
         }),
         check("lists the core tools, with their arguments", async () => {
             const { mcpUrl } = await app.connect();
@@ -408,7 +423,7 @@ export async function runConformance(app) {
     for (const c of apcConformance(app)) {
         try {
             await c.run();
-            results.push({ name: c.name, ok: true });
+            results.push({ name: c.name, ok: true, ...(c.note ? { note: c.note } : {}) });
         }
         catch (error) {
             results.push({ name: c.name, ok: false, error: error instanceof Error ? error.message : String(error) });

package/dist/shared.d.ts

@@ -41,3 +41,16 @@ export declare function resultKey(r: ToolCallResult, key: string): {
 export declare function attentionOf(r: ToolCallResult): unknown;
 /** What `tools/list` must say about the core tools (shared by the suite and the CLI). */
 export declare function checkCoreToolList(listed: unknown, coreTools: readonly string[]): void;
+/**
+ * Whether checks written for the standard `own` can judge an app that claims `claimed` in its apc.json:
+ * any version from 0.5.0 (apc.json exists since) up to `own`, and also a newer patch of the same minor
+ * (`own` 0.7.0, `claimed` 0.7.1), since a patch never changes the contract: that passes with a note. A newer
+ * minor or major may change the contract, so it fails: the checks need updating.
+ */
+export declare function standardSupport(claimed: string, own: string): {
+    ok: true;
+    note?: string;
+} | {
+    ok: false;
+    reason: string;
+};

package/dist/shared.js

@@ -2,7 +2,7 @@
  * What the in-process suite (`index.ts`) and the HTTP checks (`http.ts`) share: the error a check
  * throws, how a JSON-RPC reply is read off Streamable HTTP, and the shapes of the core's view and focus.
  */
-import { parseParams, parseTarget } from "@tineira/apc-protocol";
+import { compareStandard, parseParams, parseTarget } from "@tineira/apc-protocol";
 export class ConformanceError extends Error {
 }
 export function expect(condition, message) {
@@ -122,3 +122,23 @@ export function checkCoreToolList(listed, coreTools) {
     expect(timeout && (timeout.type === "integer" || timeout.type === "number") && timeout.minimum === 1, "wait_for_focus takes timeout_s, a whole number from 1");
     expect(!(wait.inputSchema?.required ?? []).includes("timeout_s"), "timeout_s is optional");
 }
+/**
+ * Whether checks written for the standard `own` can judge an app that claims `claimed` in its apc.json:
+ * any version from 0.5.0 (apc.json exists since) up to `own`, and also a newer patch of the same minor
+ * (`own` 0.7.0, `claimed` 0.7.1), since a patch never changes the contract: that passes with a note. A newer
+ * minor or major may change the contract, so it fails: the checks need updating.
+ */
+export function standardSupport(claimed, own) {
+    if (!/^\d+\.\d+\.\d+$/.test(claimed))
+        return { ok: false, reason: `standard is ${claimed}, not a version` };
+    if (compareStandard(claimed, "0.5.0") < 0)
+        return { ok: false, reason: `standard is ${claimed}: apc.json exists since 0.5.0` };
+    if (compareStandard(claimed, own) <= 0)
+        return { ok: true };
+    const [cMajor, cMinor] = claimed.split(".");
+    const [oMajor, oMinor] = own.split(".");
+    if (cMajor === oMajor && cMinor === oMinor) {
+        return { ok: true, note: `standard ${claimed} is a newer patch of the ${own} these checks know; a patch never changes the contract, so they apply (update @tineira/apc-conformance when you can)` };
+    }
+    return { ok: false, reason: `standard is ${claimed}, newer than the ${own} these checks know: update @tineira/apc-conformance` };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tineira/apc-conformance",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "description": "Agent Pointed Context (APC) conformance: checks an app against the standard, in process with an adapter, or live over HTTP with the apc-conformance command.",
   "keywords": [
     "apc",
@@ -45,7 +45,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@tineira/apc-protocol": "^0.7.0"
+    "@tineira/apc-protocol": "^0.7.1"
   },
   "scripts": {},
   "types": "./dist/index.d.ts",