@passioncode-ai/passioncode 0.2.38 → 0.2.40

package/payload/plugins/fabric-agent-adapter/skills/building-fabric-services/scripts/fabric-page-links.mjs

@@ -0,0 +1,144 @@
+// A service's pages as Fabric Dashboards' open_link (Fabric Agent Contract DEC-0123, PL-1 to PL-4, FAC-SEM-143;
+// `src/page-link-rules.ts` at the pin): build and read the open_link, tell a raw local address, and the findings on a
+// link a document hands a person and on a URL-mode input request. The twin of fabric_page_links.py, held to the
+// contract's answers by test/fixtures/contract/page-link-vectors.json and page-link-extra-vectors.json. It reads URLs
+// with Node's `URL` and `URLSearchParams`, as the reference does. Part of the Node service kit (FAA-65, layer L3).
+// Node 20+, no dependency.
+import { ID, INSTANCE as INSTANCE_NAME, ServiceError } from './fabric-base.mjs';
+import { isObject } from './fabric-jsvalue.mjs';
+import { credentialName, rawValues, secretValue } from './fabric-secrets.mjs';
+
+/** A service id and an instance, as `service-common.schema.json` defines them. */
+export const SERVICE_ID = ID;
+export const INSTANCE = INSTANCE_NAME;
+/** A path on the service origin, as `service-common.schema.json` `originPath` writes it: no whitespace. */
+export const ORIGIN_PATH = /^\/(?!\/)\S*$/;
+/** What the host's `safePath` refuses anywhere in a path: a backslash and a C0 or DEL control character. */
+const HOST_REFUSED = /[\\\u0000-\u001f\u007f]/;
+/** The host's limit on a path; the link around it is bounded only to keep a reader's work finite. */
+export const MAX_PAGE_PATH_LENGTH = 2048;
+export const MAX_PAGE_LINK_LENGTH = 20_000;
+const BASE = 'http://origin.invalid';
+/** A UTF-16 surrogate without its pair, which no encoding carries faithfully: it would read back as U+FFFD. */
+const LONE_SURROGATE = /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/;
+
+/** What `dashboardsLink` and `pageAnswer` throw for an id, an instance or a path the grammar refuses. */
+export class PageLinkError extends ServiceError {}
+
+/**
+ * The open_link for the service `service.instance` (PL-1): its dashboard without `path`, or the page at `path` on its
+ * origin, encoded as Fabric Dashboards' `serviceLink` encodes it. Throws PageLinkError for what the grammar refuses.
+ */
+export function dashboardsLink(service, instance, path) {
+  const problems = linkProblems(service, instance, path);
+  if (problems.length) throw new PageLinkError(problems.join('; '));
+  const base = `fabric-dashboards://service/${service}.${instance}`;
+  return path === undefined || path === null || path === '' ? base : `${base}?${new URLSearchParams({ path }).toString()}`;
+}
+
+const SHAPE = /^fabric-dashboards:\/\/service\/([^/?#]+)\/?(?:\?([^#]*))?$/;
+
+/** Read an open_link: `{ok: true, service, instance, path?}` or `{ok: false, problems}`. */
+export function parseDashboardsLink(url) {
+  if (typeof url !== 'string') return { ok: false, problems: ['not fabric-dashboards://service/<id>.<instance>[?path=<path>]'] };
+  if (url.length > MAX_PAGE_LINK_LENGTH) return { ok: false, problems: [`an open_link is at most ${MAX_PAGE_LINK_LENGTH} characters`] };
+  // The scheme and the host's verb are read without regard to case, as the host reads them.
+  const link = url.replace(/^fabric-dashboards:\/\/service\//i, 'fabric-dashboards://service/');
+  const match = SHAPE.exec(link);
+  if (!match) return { ok: false, problems: ['not fabric-dashboards://service/<id>.<instance>[?path=<path>]'] };
+  const key = match[1];
+  const dot = key.indexOf('.');
+  const service = dot < 0 ? key : key.slice(0, dot);
+  const instance = dot < 0 ? '' : key.slice(dot + 1);
+  if (!match[2]) {
+    const problems = linkProblems(service, instance);
+    return problems.length ? { ok: false, problems } : { ok: true, service, instance };
+  }
+  // The parameters as the host's URL parser reads them: a second `?` stays part of a name, and the query is
+  // percent-encoded before it is decoded.
+  const query = new URL(link).searchParams;
+  const paths = query.getAll('path');
+  if (paths.length !== 1) return { ok: false, problems: [paths.length ? 'path is given more than once' : 'an open_link names its path'] };
+  if ([...query.keys()].some((name) => name !== 'path')) return { ok: false, problems: ['an open_link carries its path and nothing else'] };
+  const path = paths[0];
+  if (path === '') return { ok: false, problems: ['the path is empty; a link to the dashboard itself names no path'] };
+  const problems = linkProblems(service, instance, path);
+  return problems.length ? { ok: false, problems } : { ok: true, service, instance, path };
+}
+
+function linkProblems(service, instance, path) {
+  const problems = [];
+  if (typeof service !== 'string' || !SERVICE_ID.test(service)) problems.push('the service is not a service id');
+  if (typeof instance !== 'string' || !INSTANCE.test(instance)) problems.push('the instance is not an instance name');
+  if (path === undefined || path === null || path === '') return problems;
+  if (typeof path !== 'string') problems.push('the path is not a path on the service origin');
+  else if (path.length > MAX_PAGE_PATH_LENGTH) problems.push(`the path is at most ${MAX_PAGE_PATH_LENGTH} characters`);
+  else if (!ORIGIN_PATH.test(path) || HOST_REFUSED.test(path) || LONE_SURROGATE.test(path) || new URL(path, BASE).origin !== BASE) problems.push('the path is not a path on the service origin');
+  else if (pathCarriesCredential(path)) problems.push("the path could carry a token or a login code; signing in is the host's");
+  return problems;
+}
+
+/** A login-code route, or a query or fragment piece that could carry a credential (FL-7: a link carries none). */
+function pathCarriesCredential(path) {
+  // The route as the service resolves it: dot segments and letter case do not hide it.
+  if (/^\/fabric\/+v1\/+login(?:\/|$)/i.test(new URL(path, BASE).pathname)) return true;
+  // The query and the fragment, a hash route's own query (`#/jobs?token=`) included, as pieces of one query.
+  const rest = path.replace(/^[^?#]*/, '').replace(/^[?#]/, '').replace(/[#?]/g, '&');
+  if (!rest) return false;
+  const pieces = [...new URLSearchParams(rest)];
+  const raw = [...rawValues(rest).values()].flat();
+  return secretValue(rest) || raw.some(secretValue) || pieces.some(([name, value]) => (value !== '' && credentialName(name)) || secretValue(value));
+}
+
+/**
+ * The hosts that only this computer reaches, as WHATWG URL writes them: 127.0.0.0/8, `[::1]`, `[::ffff:127.x.y.z]`,
+ * `localhost` and names under it, and the unspecified addresses `0.0.0.0` and `[::]` a wildcard bind reports.
+ */
+const LOOPBACK = /^(?:127(?:\.\d{1,3}){3}|0\.0\.0\.0|\[::1?\]|\[::ffff:7f[0-9a-f]{2}:[0-9a-f]{1,4}\]|localhost|[a-z0-9.-]+\.localhost)$/i;
+
+/** True for an `http` or `https` address on a loopback host: a local service's raw address. */
+export function isLoopbackPageUrl(url) {
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return false;
+  }
+  return (parsed.protocol === 'http:' || parsed.protocol === 'https:') && LOOPBACK.test(parsed.hostname.replace(/\.$/, ''));
+}
+
+/** FAC-SEM-143 for one link a document hands a person: a raw loopback address, or an open_link outside its grammar. */
+export function pageLinkFindings(url, instancePath, label) {
+  if (typeof url !== 'string') return [];
+  if (isLoopbackPageUrl(url)) return [{ code: 'FAC-SEM-143', instancePath, message: `${label} hands a person a raw local address; give Fabric Dashboards' open_link (DEC-0123 PL-1)` }];
+  // Only what a URL parser strips around a URL: C0 controls and space.
+  const bare = url.replace(/^[\u0000-\u0020]+|[\u0000-\u0020]+$/g, '');
+  if (/^\s*fabric-dashboards:/i.test(url) || parsesAsDashboards(url)) {
+    const parsed = parseDashboardsLink(bare);
+    if (!parsed.ok) return [{ code: 'FAC-SEM-143', instancePath, message: `${label} is not an open_link: ${parsed.problems.join('; ')} (DEC-0123 PL-1)` }];
+  }
+  return [];
+}
+
+function parsesAsDashboards(url) {
+  try {
+    return new URL(url).protocol === 'fabric-dashboards:';
+  } catch {
+    return false;
+  }
+}
+
+/** FAC-SEM-143 on an input request in URL mode (kind `interop-input-requests`): its `url` is a link a person opens. */
+export function inputRequestLinkFindings(value) {
+  const requests = isObject(value?.inputRequests) ? value.inputRequests : {};
+  return Object.entries(requests).flatMap(([key, request]) => {
+    const params = isObject(request) && isObject(request.params) ? request.params : {};
+    return params.mode === 'url' ? pageLinkFindings(params.url, `/inputRequests/${key}/params/url`, `input request ${key}`) : [];
+  });
+}
+
+/** Kind `page-link` (`{url}`): a link a service, its tools or its messages hand a person, such as a tool answer's `open_link`. */
+export function pageLinkRules(kind, value) {
+  if (kind !== 'page-link') return undefined;
+  return pageLinkFindings(value?.url, '/url', 'the link');
+}

package/payload/plugins/fabric-agent-adapter/skills/building-fabric-services/scripts/fabric-paths.mjs

@@ -4,7 +4,7 @@ import crypto from 'node:crypto';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-import { ID, ServiceError, expand } from './fabric-base.mjs';
+import { ID, INSTANCE, ServiceError, expand } from './fabric-base.mjs';
 import { windowsProtect } from './fabric-platform.mjs';
 
 // DEC-0032: LOCALAPPDATA, not APPDATA, so token files never roam with the profile.
@@ -39,6 +39,27 @@ export function serviceDirs(id, platform = process.platform) {
   };
 }
 
+/**
+ * One instance's folders (FAA-125, brief D16): `default` keeps serviceDirs (an existing install keeps its data, logs
+ * and lock); any other is a sibling named as its descriptor, `<id>.<instance>`, never inside the default tree.
+ */
+export function instanceDirs(id, instance = 'default', platform = process.platform) {
+  const personal = serviceDirs(id, platform);
+  if (typeof instance !== 'string' || !INSTANCE.test(instance)) throw new ServiceError(`Instance ${JSON.stringify(instance)} must match ${INSTANCE}.`);
+  if (instance === 'default') return personal;
+  const folder = `${id}.${instance}`;
+  if (platform === 'win32') {
+    const data = path.join(path.dirname(personal.data), folder);
+    return { data, logs: path.join(data, 'Logs'), cache: path.join(data, 'Cache') };
+  }
+  if (platform === 'darwin') return Object.fromEntries(Object.entries(personal).map(([key, dir]) => [key, path.join(path.dirname(dir), folder)]));
+  return {
+    data: path.join(path.dirname(personal.data), folder),
+    logs: path.join(path.dirname(path.dirname(personal.logs)), folder, 'logs'),
+    cache: path.join(path.dirname(personal.cache), folder),
+  };
+}
+
 export function ensurePrivateDir(dir) {
   fs.mkdirSync(dir, { recursive: true });
   if (process.platform === 'win32') windowsProtect(dir, { folder: true });

package/payload/plugins/fabric-agent-adapter/skills/building-fabric-services/scripts/fabric-protocols.mjs

@@ -8,10 +8,10 @@ import { credentialName, secretArgument, secretUrl, secretValue } from './fabric
 /** Each contract protocol's published revisions, oldest first (the contract's `PROTOCOL_REVISIONS`); a test holds it equal to the contract's. */
 export const PROTOCOL_REVISIONS = new Map(Object.entries({
   'access-log': ['1'], approval: ['1'], 'activity-summary': ['1'], 'agent-directory': ['1'], 'call-record': ['1'], 'coding-agents': ['1'], 'credential-decision': ['1'], 'credential-request': ['1'], 'credential-revocation': ['1'], 'enroll-token': ['1'], entitlement: ['1'], 'entitlement-key-set': ['1'], 'estate-record': ['1'], 'execution-packet': ['1'],
-  'fabric-activity': ['0.1'], 'fabric-agent-call': ['1'], 'fabric-connections': ['0.1'], 'fabric-credential-envelope': ['1'], 'fabric-load': ['0.1'], 'fabric-dashboard': ['0.1'], 'fabric-delegation': ['0.1'], 'fabric-device': ['0.1'],
+  'fabric-actions': ['0.1'], 'fabric-activity': ['0.1'], 'fabric-agent-call': ['1'], 'fabric-connections': ['0.1'], 'fabric-credential-envelope': ['1'], 'fabric-load': ['0.1'], 'fabric-dashboard': ['0.1'], 'fabric-delegation': ['0.1'], 'fabric-device': ['0.1'],
   'fabric-interop': ['0.1', '0.2'], 'fabric-local-channel': ['0.1'], 'fabric-local-runner': ['0.1'], 'fabric-operator-channel': ['0.1'],
   'fabric-package': ['1'], 'fabric-project-comms': ['0.1'], 'fabric-proposal': ['1'], 'fabric-provider': ['0.1'], 'fabric-relay': ['0.1'],
-  'fabric-secret-envelope': ['1'], 'fabric-service': ['0.1'], 'fabric-settings-backup': ['1'], heartbeat: ['1'], 'learning-note': ['1'],
+  'fabric-secret-envelope': ['1'], 'fabric-service': ['0.1'], 'fabric-settings-backup': ['1'], heartbeat: ['1'], 'learning-note': ['1'], mandate: ['1'],
   memory: ['0.1'], 'node-summary': ['1'], 'pairing-message': ['1'], pipeline: ['0.1'], 'repair-request': ['1'], 'repair-result': ['1'],
   'revocation-delta': ['1'], 'session-handoff': ['1'], 'service-load': ['1'],
   'share-registration': ['1'], 'share-registration-receipt': ['1'], 'support-quality-daily': ['1'], 'window-lease': ['1'],

package/payload/plugins/fabric-agent-adapter/skills/building-fabric-services/scripts/fabric-service.mjs

@@ -40,6 +40,7 @@ export {
   feedDataFindings,
   feedDataProblems,
 } from './fabric-protocols.mjs';
+export { ACTIONS_EXTENSION_KEY, actionDecision, actionRules, actionsExtension, actionsExtensionRules, actionsView, decisionShape } from './fabric-actions.mjs';
 export { CONNECTIONS_EXTENSION_KEY, connectionsExtension, connectionsRules, connectionsView } from './fabric-connections.mjs';
 export {
   EXIT_ALREADY_RUNNING,

package/payload/plugins/fabric-agent-adapter/skills/building-fabric-services/scripts/fabric-share.mjs

@@ -6,8 +6,8 @@
 // never throws on malformed input. Normative source: the contract's src/share-registration.ts.
 // #region share-kit-node, docs: plugins/fabric-agent-adapter/skills/building-fabric-services/references/estate-record.md#share-grants-into-an-organization
 
-import { estateTime, grantContextFindings } from './fabric-estate.mjs';
-import { sameIdentifier } from './fabric-identifiers.mjs';
+import { PERSONAL_CONTEXT, estateTime, grantContextFindings, placementGrantFindings } from './fabric-estate.mjs';
+import { normalIdentifier, sameIdentifier } from './fabric-identifiers.mjs';
 
 export const SHARE_REGISTRATION_TYPE = 'share-registration/1';
 export const SHARE_REGISTRATION_RECEIPT_TYPE = 'share-registration-receipt/1';
@@ -91,6 +91,34 @@ export function grantUsageContextFindings(value) {
   return findings;
 }
 
+/**
+ * Whether an organization's instance may run on `machineId` now (FAA-125, N-11): the placement of `agentRef` in
+ * `context` (as written; absent is personal) among that machine's packages, FAC-SEM-111 on it, and the grant's window at
+ * `atMs` (startsAt <= at < expiresAt; an unreadable instant or clock is outside it). Answers {ok: true, grant: {id,
+ * startsAt?, expiresAt?}} ({ok: true} for a personal placement) or {ok: false, code, detail} with code
+ * placement-missing, grant-refused or grant-window; never throws. Reads the revision it is given (FAC-SEM-111).
+ */
+export function instanceShareGrant(record, machineId, agentRef, context, atMs) {
+  const rec = isObject(record) ? record : {};
+  const machine = list(rec.machines).find((entry) => entry.id === machineId) ?? {};
+  const placement = list(machine.packages).find((entry) => entry.agentRef === agentRef && (entry.context === undefined ? PERSONAL_CONTEXT : entry.context) === context);
+  if (!placement) return { ok: false, code: 'placement-missing', detail: 'this machine places no such agent in that context (FAC-SEM-074)' };
+  const findings = placementGrantFindings(rec, placement);
+  if (findings.length) return { ok: false, code: 'grant-refused', detail: findings.map((f) => f.message).join('; ') };
+  if (typeof placement.grant !== 'string') return { ok: true }; // a personal placement, which names no grant
+  const id = normalIdentifier(placement.grant);
+  const grant = list(rec.shareGrants).find((g) => g.context === context && isObject(g.meta) && typeof g.meta.id === 'string' && normalIdentifier(g.meta.id) === id);
+  if (!grant) return { ok: false, code: 'grant-refused', detail: 'the record has no share grant for this placement' }; // defensive, as in Python
+  const answer = { id: grant.meta.id };
+  for (const name of ['startsAt', 'expiresAt']) if (grant[name] !== undefined) answer[name] = grant[name];
+  const starts = answer.startsAt === undefined ? undefined : estateTime(answer.startsAt);
+  const expires = answer.expiresAt === undefined ? undefined : estateTime(answer.expiresAt);
+  if ((starts !== undefined && !(starts <= atMs)) || (expires !== undefined && !(atMs < expires))) {
+    return { ok: false, code: 'grant-window', detail: "now is outside the share grant's window, or an instant cannot be read" };
+  }
+  return { ok: true, grant: answer };
+}
+
 /** Kinds grant, org-share-grants, share-registration and device-attribution (045's grant.usage clause); undefined otherwise. */
 export function shareRules(kind, value) {
   if (kind === 'grant') return grantFindings(value, '');

package/payload/plugins/fabric-agent-adapter/skills/building-fabric-services/scripts/fabric-supervisors.mjs

@@ -6,7 +6,7 @@ import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { credentialName, secretArgument, secretUrl, secretValue } from './fabric-secrets.mjs';
 import { DRAIN_SECONDS, SUPERVISOR_ENV, ServiceError, TASK, UNIT } from './fabric-base.mjs';
-import { atomicWrite, serviceDirs } from './fabric-paths.mjs';
+import { atomicWrite, instanceDirs } from './fabric-paths.mjs';
 import { SUPERVISOR_ARG, markerArguments } from './fabric-lock.mjs';
 import { URI } from './fabric-backups.mjs';
 
@@ -370,14 +370,15 @@ export async function launchdInstall(label, plistPath, plistText, { origin, serv
 /**
  * Symmetric with launchdInstall (LC-14): bootout and WAIT until the job is gone, remove the plist, and reset the
  * override to enabled — launchctl has no verb that deletes an override, and a leftover `disabled` would keep a later
- * fresh install off. Data stays unless `purge` (then `serviceId` names whose data, logs and cache go). A job still
+ * fresh install off. Data stays unless `purge` (then `serviceId` names whose data, logs and cache go, and `instance` which
+ * instance's, so one context's purge never reaches another's, FAA-125). A job still
  * loaded at `timeout` seconds throws, leaving the plist and the data in place.
  */
-export async function launchdUninstall(label, plistPath, { timeout = 30, purge = false, serviceId, run = defaultRun, platform = process.platform, uid, sleep = pause } = {}) {
+export async function launchdUninstall(label, plistPath, { timeout = 30, purge = false, serviceId, instance = 'default', run = defaultRun, platform = process.platform, uid, sleep = pause } = {}) {
   const domain = launchdDomain(platform, uid);
   launchdLabel(label);
   if (purge && !serviceId) throw new ServiceError('purge needs the service id whose data, logs and cache to remove.');
-  const dirs = purge ? serviceDirs(serviceId, platform) : {};
+  const dirs = purge ? instanceDirs(serviceId, instance, platform) : {}; // one instance's folders only (FAA-125)
   const opts = { run, platform, uid };
   const target = `${domain}/${label}`;
   run(['launchctl', 'bootout', target]);

package/payload/plugins/fabric-agent-adapter/skills/building-fabric-services/scripts/fabric_a2a.py

@@ -0,0 +1,209 @@
+"""The reading side of an A2A Agent Card (DEC-0122): the well-known document's `surfaces.a2a` member, read as the
+contract's schema reads it (`a2a_surface_findings`, `a2a_view`; `a2a_surface` builds one), and what a public card must
+not carry (`agent_card_findings`): no member about the running process, no secret, no `securitySchemes` entry naming
+the descriptor's token header, every Fabric extension `required: false` (or absent, which A2A reads as false), and interface URLs where the placement puts
+them. Serving a card, the A2A binding and a client are not here (FAA-10). Part of the service kit (layer L3).
+Standard library only."""
+from __future__ import annotations
+
+import re
+from typing import Any, Dict, List, Optional
+
+import sys as _sys  # noqa: E402
+from pathlib import Path as _Path  # noqa: E402
+if str(_Path(__file__).resolve().parent) not in _sys.path:  # the kit loads from any working directory (FAA-65)
+    _sys.path.insert(0, str(_Path(__file__).resolve().parent))
+
+from fabric_base import ServiceError  # noqa: E402
+from fabric_jsvalue import js_keys  # noqa: E402
+from fabric_secrets import secret_value  # noqa: E402
+
+#: A2A 1.0 section 8.2: where a peer looks for the public card.
+A2A_SURFACE_PATH = "/.well-known/agent-card.json"
+#: The A2A version the contract pins (the A2A peer profile); `surfaces.a2a.protocolVersion` is this constant.
+A2A_PROTOCOL_VERSION = "1.0"
+#: The contract's extension namespace (decision D6): an extension whose uri starts here is a Fabric fact.
+FABRIC_EXTENSION_PREFIX = "https://fabric.passioncode.ai/"
+#: The well-known document's members about the running process, which a public card never carries (DEC-0122 item 2).
+PROCESS_MEMBERS = ("build", "process", "pid", "status", "summary", "degraded")
+MAX_PATH = 2048  # service-common.schema.json originPath maxLength, counted in code points as ajv counts it
+
+# JavaScript's \s (the schema's pattern runs under ajv), not Python's: U+FEFF is one, U+001C and U+0085 are not.
+_JS_SPACE = ("\t\n\x0b\x0c\r              "
+             "

  　")
+_ORIGIN_PATH = re.compile("^/(?!/)[^%s]*\\Z" % _JS_SPACE)
+_HTTPS = re.compile(r"^https://", re.IGNORECASE)
+
+
+def _pointer(*parts: Any) -> str:
+    return "".join("/" + str(p).replace("~", "~0").replace("/", "~1") for p in parts)
+
+
+def _ascii_lower(text: str) -> str:
+    return re.sub("[A-Z]", lambda m: m.group(0).lower(), text)
+
+
+def _finding(path: str, keyword: str, message: str) -> Dict[str, str]:
+    return {"instancePath": path, "keyword": keyword, "message": message}
+
+
+def a2a_surface_findings(value: Any, base: str = "/surfaces/a2a") -> List[Dict[str, str]]:
+    """`surfaces.a2a` against service-well-known.schema.json at the pin, in ajv's order: each finding's instancePath
+    and keyword are the schema error's (test/fixtures/contract/a2a-vectors.json), with a sentence."""
+    if not isinstance(value, dict):
+        return [_finding(base, "type", "surfaces.a2a is an object {path, protocolVersion}")]
+    found = [_finding(base, "required", "surfaces.a2a has no %s" % k) for k in ("path", "protocolVersion") if k not in value]
+    found += [_finding(base, "additionalProperties", "surfaces.a2a has no member %s: the card names its interfaces, "
+                       "bindings and security schemes (DEC-0122)" % k)
+              for k in value if k not in ("path", "protocolVersion")]
+    if "path" in value:
+        path = value["path"]
+        if not isinstance(path, str):
+            found.append(_finding(base + "/path", "type", "surfaces.a2a.path is a string"))
+        else:
+            if len(path) > MAX_PATH:
+                found.append(_finding(base + "/path", "maxLength", "surfaces.a2a.path is longer than %d characters" % MAX_PATH))
+            if not _ORIGIN_PATH.match(path):
+                found.append(_finding(base + "/path", "pattern", "surfaces.a2a.path is not a path on the service origin "
+                                      "(one leading /, no whitespace)"))
+    if "protocolVersion" in value and not (isinstance(value["protocolVersion"], str) and value["protocolVersion"] == A2A_PROTOCOL_VERSION):
+        found.append(_finding(base + "/protocolVersion", "const", "surfaces.a2a.protocolVersion is %s, the A2A version the "
+                              "contract pins" % A2A_PROTOCOL_VERSION))
+    return found
+
+
+def a2a_surface_problems(value: Any) -> List[str]:
+    """The findings of a2a_surface_findings as sentences; empty when the member is valid."""
+    return [f["message"] for f in a2a_surface_findings(value)]
+
+
+def a2a_surface(path: str = A2A_SURFACE_PATH) -> Dict[str, str]:
+    """The `surfaces.a2a` member for a service that serves its public card at `path` (DEC-0122 item 1)."""
+    surface = {"path": path, "protocolVersion": A2A_PROTOCOL_VERSION}
+    problems = a2a_surface_problems(surface)
+    if problems:
+        raise ServiceError("surfaces.a2a: %s." % "; ".join(problems))
+    return surface
+
+
+def a2a_view(wk: Any) -> Dict[str, Any]:
+    """What a host reads of a well-known document's A2A member; never raises. `declared` is whether `surfaces.a2a`
+    is present, `valid` whether it is the schema's, `path` the card's path when it is, `findings` the schema's."""
+    surfaces = wk.get("surfaces") if isinstance(wk, dict) else None
+    if not isinstance(surfaces, dict) or "a2a" not in surfaces:
+        return {"declared": False, "valid": False, "path": None, "protocolVersion": None, "findings": []}
+    findings = a2a_surface_findings(surfaces["a2a"])
+    valid = not findings
+    return {"declared": True, "valid": valid, "path": surfaces["a2a"]["path"] if valid else None,
+            "protocolVersion": A2A_PROTOCOL_VERSION if valid else None, "findings": findings}
+
+
+def _card(code: str, path: str, message: str) -> Dict[str, str]:
+    return {"code": code, "instancePath": path, "message": message}
+
+
+def _secrets(card: Dict[str, Any]) -> List[Dict[str, str]]:
+    """Every string the card holds that is shaped like a credential, by its place; walked without recursion, in the
+    order JavaScript lists keys, so both twins name the same places in the same order."""
+    found: List[Dict[str, str]] = []
+    stack: List[Any] = [(card, "")]
+    while stack:
+        node, path = stack.pop()
+        if isinstance(node, str):
+            if secret_value(node):
+                found.append(_card("secret", path, "%s holds a value shaped like a credential: a public card carries no "
+                                   "secret (DEC-0122 item 2)" % (path or "the card")))
+        elif isinstance(node, dict):
+            stack.extend((node[k], path + _pointer(k)) for k in reversed(js_keys(node)))
+        elif isinstance(node, list):
+            stack.extend((node[i], path + _pointer(i)) for i in reversed(range(len(node))))
+    return found
+
+
+def _descriptor_schemes(card: Dict[str, Any], header: str) -> List[Dict[str, str]]:
+    """D5: a securitySchemes entry that is an API key in the descriptor's own header. With Authorization (the
+    default) the card cannot show the token, so nothing is reported."""
+    schemes = card.get("securitySchemes")
+    if not isinstance(schemes, dict) or not header or _ascii_lower(header) == "authorization":
+        return []
+    found = []
+    for name in js_keys(schemes):
+        scheme = schemes[name]
+        if not isinstance(scheme, dict):
+            continue
+        key = scheme.get("apiKeySecurityScheme")  # A2A 1.0: one wrapper member per kind
+        if isinstance(key, dict):
+            location, named = key.get("location"), key.get("name")
+        elif scheme.get("type") == "apiKey":  # the OpenAPI shape of A2A before 1.0
+            location, named = scheme.get("in"), scheme.get("name")
+        else:
+            continue
+        if location == "header" and isinstance(named, str) and _ascii_lower(named) == _ascii_lower(header):
+            found.append(_card("descriptor-token-scheme", _pointer("securitySchemes", name),
+                               "securitySchemes.%s is an API key in %s, the descriptor's token header: an A2A interface "
+                               "never takes the descriptor's token (DEC-0122 item 3)" % (name, header)))
+    return found
+
+
+def _fabric_extensions(card: Dict[str, Any]) -> List[Dict[str, str]]:
+    """D6: an extension under the contract's namespace is not required (A2A 1.0 section 4.4.4): `required` false or
+    absent, which A2A reads as false (a protobuf-written card drops a false default); true or a non-boolean is a finding."""
+    capabilities = card.get("capabilities")
+    extensions = capabilities.get("extensions") if isinstance(capabilities, dict) else None
+    if not isinstance(extensions, list):
+        return []
+    found = []
+    for i, extension in enumerate(extensions):
+        uri = extension.get("uri") if isinstance(extension, dict) else None
+        if not isinstance(uri, str) or _ascii_lower(uri[:len(FABRIC_EXTENSION_PREFIX)]) != FABRIC_EXTENSION_PREFIX:
+            continue
+        if "required" in extension and extension["required"] is not False:
+            found.append(_card("fabric-extension-required", _pointer("capabilities", "extensions", i),
+                               "the Fabric extension at capabilities.extensions[%d] is required, so a peer that does not "
+                               "know it cannot call; it carries required: false (DEC-0122 item 4)" % i))
+    return found
+
+
+def _interfaces(card: Dict[str, Any], origin: Optional[str], remote: bool) -> List[Dict[str, str]]:
+    """Where the card's interfaces are (DEC-0122 item 2): on a local placement on the service's loopback origin as
+    written, on a remote one https; every one A2A 1.0."""
+    interfaces = card.get("supportedInterfaces")
+    if not isinstance(interfaces, list) or not interfaces:
+        return [_card("interfaces-missing", "/supportedInterfaces", "the card names no supportedInterfaces: A2A 1.0 "
+                      "lists a card's interfaces there")]
+    found = []
+    for i, interface in enumerate(interfaces):
+        place = _pointer("supportedInterfaces", i)
+        url = interface.get("url") if isinstance(interface, dict) else None
+        if not isinstance(url, str):
+            found.append(_card("interface-shape", place, "supportedInterfaces[%d] is not an interface with a url" % i))
+            continue
+        if remote:
+            if not _HTTPS.match(url):
+                found.append(_card("interface-scheme", place + "/url", "supportedInterfaces[%d].url is not https: a "
+                                   "loopback or plain-http interface is admitted on a local placement only" % i))
+        elif origin and not (url == origin or url.startswith(origin + "/")):
+            found.append(_card("interface-origin", place + "/url", "supportedInterfaces[%d].url is not on the service "
+                               "origin %s, where a peer on this computer reaches it" % (i, origin)))
+        if not (isinstance(interface.get("protocolVersion"), str) and interface["protocolVersion"] == A2A_PROTOCOL_VERSION):
+            found.append(_card("interface-version", place + "/protocolVersion", "supportedInterfaces[%d] does not expose "
+                               "A2A %s, the version surfaces.a2a names" % (i, A2A_PROTOCOL_VERSION)))
+    return found
+
+
+def agent_card_findings(card: Any, *, origin: Optional[str] = None, remote: bool = False,
+                        descriptor_header: Optional[str] = "Authorization") -> List[Dict[str, str]]:
+    """What a public Agent Card must not carry or say (DEC-0122 items 2 to 4; decisions D5, D6), each finding
+    {code, instancePath, message} naming the place and never the value. `origin` is the service origin the card was
+    read on (its interfaces' place on a local placement; omitted, the place is not judged), `remote` the placement,
+    `descriptor_header` the descriptor's `auth.header` (default Authorization). It reads the card only: whether an
+    interface accepts the token cannot be seen without sending it, which DEC-0122 forbids."""
+    if not isinstance(card, dict):
+        return [_card("card-shape", "", "the card is not a JSON object")]
+    found = [_card("process-member", _pointer(k), "the card carries %s, a member about the running process: a public "
+                   "card carries none (DEC-0122 item 2)" % k) for k in PROCESS_MEMBERS if k in card]
+    found += _secrets(card)
+    found += _descriptor_schemes(card, descriptor_header if isinstance(descriptor_header, str) else "")
+    found += _fabric_extensions(card)
+    found += _interfaces(card, origin, remote)
+    return found