@passioncode-ai/fabric-agent-adapter 0.24.0 → 0.26.0

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

@@ -0,0 +1,156 @@
+// Identifier equality (contract DEC-0076): two identifiers are the same when their normal forms are equal. A port of the
+// contract's src/identifiers.ts (types removed), held to its fixtures/vectors/identifiers.json; the twin of
+// fabric_identifiers.py. Nothing here throws.
+
+const UNRESERVED = "A-Za-z0-9\\-._~";
+const SUB_DELIMS = "!$&'()*+,;=";
+const PCT = "%[0-9A-Fa-f]{2}";
+/** `*( <chars> / pct-encoded )` — each a single character class beside one fixed triplet, so the match is linear. */
+const run = (chars) => new RegExp(`^(?:[${chars}]|${PCT})*$`);
+const USERINFO = run(`${UNRESERVED}${SUB_DELIMS}:`);
+const REG_NAME = run(`${UNRESERVED}${SUB_DELIMS}`);
+const PATH = run(`${UNRESERVED}${SUB_DELIMS}:@/`);
+const QUERY = run(`${UNRESERVED}${SUB_DELIMS}:@/?`);
+const PORT = /^[0-9]*$/;
+const SCHEME = /^[A-Za-z][A-Za-z0-9+.-]*$/;
+
+// RFC 3986 §3.2.2: IP-literal = "[" ( IPv6address / IPvFuture ) "]".
+const H16 = "[0-9A-Fa-f]{1,4}";
+const DEC_OCTET = "(?:25[0-5]|2[0-4][0-9]|1[0-9]{2}|[1-9]?[0-9])";
+const IPV4 = `${DEC_OCTET}(?:\\.${DEC_OCTET}){3}`;
+const LS32 = `(?:${H16}:${H16}|${IPV4})`;
+const IPV6 = [
+  `(?:${H16}:){6}${LS32}`,
+  `::(?:${H16}:){5}${LS32}`,
+  `(?:${H16})?::(?:${H16}:){4}${LS32}`,
+  `(?:(?:${H16}:){0,1}${H16})?::(?:${H16}:){3}${LS32}`,
+  `(?:(?:${H16}:){0,2}${H16})?::(?:${H16}:){2}${LS32}`,
+  `(?:(?:${H16}:){0,3}${H16})?::${H16}:${LS32}`,
+  `(?:(?:${H16}:){0,4}${H16})?::${LS32}`,
+  `(?:(?:${H16}:){0,5}${H16})?::${H16}`,
+  `(?:(?:${H16}:){0,6}${H16})?::`,
+].join("|");
+const IP_LITERAL = new RegExp(`^\\[(?:${IPV6}|[Vv][0-9A-Fa-f]+\\.[${UNRESERVED}${SUB_DELIMS}:]+)\\]$`);
+
+// RFC 8141 §2: NID = (alphanum) 0*30(ldh) (alphanum), then ":" and a non-empty NSS.
+const URN_NAME = /^([A-Za-z0-9][A-Za-z0-9-]{0,30}[A-Za-z0-9]):(.+)$/s;
+
+/** Percent-encoding hex upper-cased (§6.2.2.1), and unreserved characters decoded unless `keepEncoded` (§6.2.2.2). */
+function percent(text, keepEncoded = false) {
+  return text.replace(/%([0-9A-Fa-f]{2})/g, (_, hex) => {
+    const char = String.fromCharCode(Number.parseInt(hex, 16));
+    return !keepEncoded && /^[A-Za-z0-9\-._~]$/.test(char) ? char : `%${hex.toUpperCase()}`;
+  });
+}
+
+/**
+ * A rootless path (`agent:./x`) loses its leading "./" and "../" segments — §5.2.4's step A — while what is left stays
+ * rootless: not empty and not beginning with "/". Dot segments further in are kept, because removing them by §5.2.4 can
+ * turn a rootless path into an absolute one (`a/../b` → `/b`). That narrowing is the contract's own, under RFC 3986
+ * §6.1's aim of no false positives (DEC-0076).
+ */
+function stripLeadingDots(path) {
+  let start = 0;
+  while (path.startsWith("./", start) || path.startsWith("../", start)) start += path.startsWith("./", start) ? 2 : 3;
+  const rest = path.slice(start);
+  return rest === "" || rest.startsWith("/") ? path : rest;
+}
+
+/**
+ * RFC 3986 §5.2.4 remove_dot_segments, over a path whose `.` and `..` are already decoded. Its input buffer is read
+ * segment by segment: the path split on "/" gives the same steps without copying the rest of the input at each one.
+ */
+function removeDotSegments(path) {
+  const absolute = path.startsWith("/");
+  const segments = (absolute ? path.slice(1) : path).split("/");
+  const output = [];
+  segments.forEach((segment, index) => {
+    const last = index === segments.length - 1;
+    if (segment === "." || segment === "..") {
+      if (segment === ".." && output.length > 0) output.pop();
+      // A dot segment that ends the path leaves the path ending in "/" (§5.2.4 steps B and C on "/." and "/..").
+      if (last) output.push("");
+      return;
+    }
+    output.push(segment);
+  });
+  return (absolute ? "/" : "") + output.join("/");
+}
+
+
+/** RFC 3986 Appendix B's split, then each component checked against its §3 production; undefined when one fails. */
+function parse(text) {
+  const match = /^([^:/?#]+):(?:\/\/([^/?#]*))?([^?#]*)(?:\?([^#]*))?(?:#(.*))?$/s.exec(text);
+  if (!match) return undefined;
+  const [, scheme, authority, path, query, fragment] = match;
+  if (!SCHEME.test(scheme) || !PATH.test(path)) return undefined;
+  if (query !== undefined && !QUERY.test(query)) return undefined;
+  if (fragment !== undefined && !QUERY.test(fragment)) return undefined;
+  if (authority !== undefined && !authorityParts(authority)) return undefined;
+  // An empty path with no authority (`x:`, RFC 3986's path-empty) is left as it is: the schema's `format: uri` refuses
+  // it, so no admitted value has it. (A path never begins with "//" here: Appendix B's split reads that as an authority.)
+  if (authority === undefined && path === "") return undefined;
+  return { scheme, authority, path, query, fragment };
+}
+
+function authorityParts(authority) {
+  const at = authority.lastIndexOf("@");
+  const userinfo = at === -1 ? undefined : authority.slice(0, at);
+  const hostPort = at === -1 ? authority : authority.slice(at + 1);
+  const bracket = hostPort.startsWith("[") ? hostPort.indexOf("]") : -1;
+  const colon = hostPort.indexOf(":", bracket === -1 ? 0 : bracket);
+  const host = colon === -1 ? hostPort : hostPort.slice(0, colon);
+  const port = colon === -1 ? undefined : hostPort.slice(colon + 1);
+  if (userinfo !== undefined && !USERINFO.test(userinfo)) return undefined;
+  if (port !== undefined && !PORT.test(port)) return undefined;
+  if (host.startsWith("[") ? !IP_LITERAL.test(host) : !REG_NAME.test(host)) return undefined;
+  return { userinfo, host, port };
+}
+
+/** RFC 8141 §3.1: `urn` and the NID lower-cased, hex upper-cased, nothing decoded; r-, q- and f-components ignored. */
+function urnForm(parts) {
+  const name = URN_NAME.exec(parts.path);
+  const path = name ? `${name[1].toLowerCase()}:${percent(name[2], true)}` : percent(parts.path, true);
+  // A "?" not followed by "+" or "=" is no URN component (RFC 8141 §2): it is kept, never dropped unread.
+  const query = parts.query !== undefined && !/^[+=]/.test(parts.query) ? `?${percent(parts.query, true)}` : "";
+  const authority = parts.authority !== undefined ? `//${percent(parts.authority, true)}` : "";
+  return `urn:${authority}${path}${query}`;
+}
+
+function genericForm(parts) {
+  let authority = "";
+  if (parts.authority !== undefined) {
+    const { userinfo, host, port } = authorityParts(parts.authority);
+    // The host is case-insensitive (§3.2.2); its remaining percent triplets keep upper-case hex.
+    const lowered = percent(host).toLowerCase().replace(/%[0-9a-f]{2}/g, (triplet) => triplet.toUpperCase());
+    authority = `//${userinfo !== undefined ? `${percent(userinfo)}@` : ""}${lowered}${port !== undefined ? `:${port}` : ""}`;
+  }
+  const decoded = percent(parts.path);
+  const hierarchical = parts.authority !== undefined || decoded.startsWith("/");
+  let path = hierarchical ? removeDotSegments(decoded) : stripLeadingDots(decoded);
+  // A path left starting with "//" and no authority would read as one: keep the decoded path instead.
+  if (parts.authority === undefined && path.startsWith("//")) path = decoded;
+  const query = parts.query !== undefined ? `?${percent(parts.query)}` : "";
+  const fragment = parts.fragment !== undefined ? `#${percent(parts.fragment)}` : "";
+  return `${parts.scheme.toLowerCase()}:${authority}${path}${query}${fragment}`;
+}
+
+/**
+ * The normal form of an identifier: a URI's syntax-normalized form (RFC 3986 §6.2.2; RFC 8141 §3.1 for `urn:`), any
+ * other string as it is, and undefined for a value that is not a string.
+ */
+export function normalIdentifier(value) {
+  if (typeof value !== "string") return undefined;
+  const parts = parse(value);
+  if (!parts) return value;
+  return parts.scheme.toLowerCase() === "urn" ? urnForm(parts) : genericForm(parts);
+}
+
+/**
+ * Two identifiers are the same when their normal forms are equal (DEC-0076). A value that is not a string is no
+ * identifier and is compared as it is (`===`), so a rule reads a schema-invalid member exactly as it did before.
+ */
+export function sameIdentifier(a, b) {
+  if (typeof a !== "string" || typeof b !== "string") return a === b;
+  return normalIdentifier(a) === normalIdentifier(b);
+}

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

@@ -4,6 +4,7 @@
 // the well-known `configuration` with its summary tiles ("Runner & model"). No dependencies.
 
 import { spawnSync } from 'node:child_process';
+import { normalIdentifier, sameIdentifier } from './fabric-identifiers.mjs';
 import fs from 'node:fs';
 import path from 'node:path';
 import { secretValue } from './fabric-secrets.mjs';
@@ -210,7 +211,8 @@ export const PROBE_RESULTS = Object.freeze(['not-catalogued', 'not-admitted', 'n
 
 const routeCandidates = (value) => (Array.isArray(value?.candidates) ? value.candidates.filter(isObject) : []);
 const objectAt = (value, key) => (isObject(value?.[key]) ? value[key] : {});
-const refKey = (ref) => (isObject(ref) ? `${String(ref.id)}@${String(ref.revision)}#${String(ref.contentHash)}` : '');
+// A revision reference compared whole; its id is an identifier, so it enters the key in its normal form (DEC-0076).
+const refKey = (ref) => (isObject(ref) ? `${String(normalIdentifier(ref.id) ?? ref.id)}@${String(ref.revision)}#${String(ref.contentHash)}` : '');
 const sameRef = (a, b) => refKey(a) !== '' && refKey(a) === refKey(b);
 
 function runnerRoute(value) {
@@ -229,7 +231,7 @@ function runnerRoute(value) {
 function routeBundle(value) {
   const route = objectAt(value, 'route');
   const admissions = Array.isArray(value.admissions) ? value.admissions.filter(isObject) : [];
-  const admitted = new Set(admissions.filter((a) => a.state === 'admitted' && a.capability === route.capability).map((a) => refKey(a.provider)));
+  const admitted = new Set(admissions.filter((a) => a.state === 'admitted' && sameIdentifier(a.capability, route.capability)).map((a) => refKey(a.provider)));
   const findings = [];
   routeCandidates(route).forEach((candidate, index) => {
     const key = refKey(candidate.provider);
@@ -238,8 +240,9 @@ function routeBundle(value) {
   if (isObject(value.binding)) {
     const binding = value.binding;
     const disagree = (where, message) => findings.push(finding('FAC-SEM-032', `/binding/${where}`, message));
-    if (binding.project !== route.project) disagree('project', `the binding is for ${String(binding.project)}, the route for ${String(route.project)}`);
-    if (binding.capability !== route.capability) disagree('capability', `the binding binds ${String(binding.capability)}, the route orders ${String(route.capability)}`);
+    // DEC-0076: project and capability are identifiers, compared by normal form.
+    if (!sameIdentifier(binding.project, route.project)) disagree('project', `the binding is for ${String(binding.project)}, the route for ${String(route.project)}`);
+    if (!sameIdentifier(binding.capability, route.capability)) disagree('capability', `the binding binds ${String(binding.capability)}, the route orders ${String(route.capability)}`);
     if (binding.profileKind !== 'local-runner') disagree('profileKind', `a runner route serves the local-runner profile, not ${String(binding.profileKind)}`);
     if (!routeCandidates(route).some((c) => sameRef(c.provider, binding.provider))) disagree('provider', `the binding's provider ${refKey(binding.provider)} is not a candidate of the route`);
     if (binding.runnerRoute !== undefined && !sameRef(binding.runnerRoute, route.meta)) disagree('runnerRoute', `the binding pins ${refKey(binding.runnerRoute)}, not this route ${refKey(route.meta)}`);
@@ -263,8 +266,8 @@ function routeEvent(value) {
   const findings = [];
   const wrong = (where, message) => findings.push(finding('FAC-SEM-034', `/event${where}`, message));
   if (!sameRef(event.route, route.meta)) wrong('/route', `the event names route ${refKey(event.route)}, not ${refKey(route.meta)}`);
-  if (event.project !== route.project) wrong('/project', `the event is for ${String(event.project)}, the route for ${String(route.project)}`);
-  if (event.capability !== route.capability) wrong('/capability', `the event names ${String(event.capability)}, the route orders ${String(route.capability)}`);
+  if (!sameIdentifier(event.project, route.project)) wrong('/project', `the event is for ${String(event.project)}, the route for ${String(route.project)}`);
+  if (!sameIdentifier(event.capability, route.capability)) wrong('/capability', `the event names ${String(event.capability)}, the route orders ${String(route.capability)}`);
   const indexOf = (ref) => (typeof ref.index === 'number' && Number.isInteger(ref.index) ? ref.index : -1);
   const candidateAt = (ref, where) => {
     const index = indexOf(ref);

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

@@ -9,7 +9,7 @@ import fs from 'node:fs';
 import net from 'node:net';
 import os from 'node:os';
 import path from 'node:path';
-import { credentialName, secretArgument, secretValue } from './fabric-secrets.mjs';
+import { credentialName, secretArgument, secretUrl, secretValue } from './fabric-secrets.mjs';
 
 export const PROTOCOL = 'fabric-service/0.1';
 export const EXTENSION_KEY = 'https://fabric.passioncode.ai/agent-contract/extensions/service/0.1';
@@ -818,7 +818,7 @@ export function configurationProblems(doc) {
   return problems;
 }
 
-export function buildWellKnown({ id, instance, name, version, build, startedAt, status, degraded = [], surfaces, summary, updateAvailable = null, pid = process.pid, extensions, configuration }) {
+export function buildWellKnown({ id, instance, name, version, build, startedAt, status, degraded = [], surfaces, summary, updateAvailable = null, pid = process.pid, extensions, configuration, protocols }) {
   if (!STATUSES.includes(status)) throw new ServiceError(`status must be one of ${STATUSES.join(', ')}.`);
   if (!surfaces?.events) throw new ServiceError('surfaces.events is required.');
   if (!(build?.commit || build?.digest)) throw new ServiceError('build needs a commit or a digest.');
@@ -844,12 +844,132 @@ export function buildWellKnown({ id, instance, name, version, build, startedAt,
     if (problems.length) throw new ServiceError(`configuration: ${problems.join('; ')}.`);
     doc.configuration = configuration;
   }
+  if (protocols !== undefined) {
+    // DEC-0067: the revisions this service accepts. The document is closed for a reader pinned before DEC-0067, so a
+    // service lists them only once its hosts are pinned at or after it.
+    const problems = protocolsFindings(protocols);
+    if (problems.length) throw new ServiceError(`protocols: ${problems.map((f) => f.message).join('; ')}.`);
+    doc.protocols = [...protocols];
+  }
   return doc;
 }
 
 // An event about traced work carries traceId and spanId together (fabric-interop/0.1 C3.4 c);
 // traceIds(traceparent) in fabric-interop.mjs gives both.
-export function makeEvent(id, at, kind, level, text, { subject, link, notify, traceId, spanId } = {}) {
+// --- DEC-0067: protocol revisions; DEC-0070: an event's machine-readable data ---------------------------------------
+
+/** 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'], 'estate-record': ['1'], 'execution-packet': ['1'],
+  'fabric-activity': ['0.1'], 'fabric-dashboard': ['0.1'], 'fabric-delegation': ['0.1'], 'fabric-device': ['0.1'],
+  'fabric-interop': ['0.1'], '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'],
+  memory: ['0.1'], pipeline: ['0.1'], 'revocation-delta': ['1'], 'session-handoff': ['1'], 'window-lease': ['1'],
+}));
+export const MAX_PROTOCOLS = 64;
+const REVISION = /^([a-z][a-z0-9.-]{0,63})\/([0-9]{1,4}(?:\.[0-9]{1,4}){0,2})$/;
+
+/** `<name>/<revision>` split, or undefined. */
+export function parseRevision(value) {
+  const m = typeof value === 'string' ? REVISION.exec(value) : null;
+  return m ? { name: m[1], revision: m[2] } : undefined;
+}
+
+/** The revisions a receiver implementing `name` up to `newest` accepts: N and, when the register has one, N−1. */
+export function acceptedRevisions(name, newest) {
+  const known = PROTOCOL_REVISIONS.get(name);
+  if (!known?.length) return [];
+  const top = newest === undefined ? known.length - 1 : known.indexOf(newest);
+  if (top < 0) return [];
+  return known.slice(Math.max(0, top - 1), top + 1).reverse().map((r) => `${name}/${r}`);
+}
+
+/**
+ * A receiver's answer to a document naming `received` (DEC-0067, the contract's `negotiateRevision`): `{ok: true}`, the
+ * `schema-unsupported` refusal naming what was received (at most 80 characters) and the accepted revisions of that
+ * protocol (all of them when it names none the receiver reads), or `{fault: 'no-accepted-revisions'}`.
+ */
+export function negotiateRevision(received, accepted) {
+  const usable = [...new Set((Array.isArray(accepted) ? accepted : []).filter((e) => parseRevision(e) !== undefined))].slice(0, MAX_PROTOCOLS);
+  if (!usable.length) return { fault: 'no-accepted-revisions' };
+  if (typeof received === 'string' && usable.includes(received)) return { ok: true };
+  const parsed = parseRevision(received);
+  const same = parsed ? usable.filter((e) => parseRevision(e)?.name === parsed.name) : [];
+  return { error: { code: 'schema-unsupported', message: 'this receiver does not read that protocol revision',
+    data: { protocol: typeof received === 'string' ? Array.from(received).slice(0, 80).join('') : '', accepted: same.length ? same : usable } } };
+}
+
+/** FAC-SEM-099 (DEC-0067): 1 to 64 entries, each once; at most N and N−1 of one protocol, consecutive in the register. */
+export function protocolsFindings(protocols, prefix = '/protocols') {
+  const flag = (instancePath, message) => ({ code: 'FAC-SEM-099', instancePath, message });
+  if (!Array.isArray(protocols)) return [flag(prefix, 'protocols is a list of protocol revisions')];
+  if (protocols.length === 0 || protocols.length > MAX_PROTOCOLS) return [flag(prefix, `protocols lists 1 to ${MAX_PROTOCOLS} revisions`)];
+  const findings = [];
+  const byName = new Map();
+  const seen = new Set();
+  protocols.forEach((entry, i) => {
+    const at = `${prefix}/${i}`;
+    const parsed = parseRevision(entry);
+    if (!parsed) { findings.push(flag(at, 'a protocol revision is <name>/<revision>, such as fabric-service/0.1')); return; }
+    if (seen.has(entry)) { findings.push(flag(at, 'each protocol revision once')); return; }
+    seen.add(entry);
+    const known = PROTOCOL_REVISIONS.get(parsed.name);
+    if (known && !known.includes(parsed.revision)) { findings.push(flag(at, `${parsed.name} has no published revision ${parsed.revision}`)); return; }
+    const indices = byName.get(parsed.name) ?? [];
+    indices.push(known ? known.indexOf(parsed.revision) : -1);
+    byName.set(parsed.name, indices);
+    if (indices.length > 2) findings.push(flag(at, 'at most 2 revisions of one protocol: N and N−1'));
+    else if (known && indices.length === 2 && Math.abs(indices[0] - indices[1]) !== 1) findings.push(flag(at, 'two revisions of one protocol are N and N−1, consecutive in the register'));
+  });
+  return findings;
+}
+
+const SCHEMA_URI = /^[A-Za-z][A-Za-z0-9+.-]*:\S+$/;
+const scalar = (v) => v === null || typeof v === 'boolean' || (typeof v === 'number' && Number.isFinite(v)) || (typeof v === 'string' && Array.from(v).length <= 500);
+const isPlain = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+const pointerToken = (name) => String(name).replace(/~/g, '~0').replace(/\//g, '~1');
+
+/** FAC-SEM-101 over an events page (the contract's `feedDataFindings`): no credential's name or shape in an event's data. */
+export function feedDataFindings(page) {
+  const findings = [];
+  const check = (named, member, at) => {
+    if (typeof member !== 'string') return;
+    if (named) findings.push({ code: 'FAC-SEM-101', instancePath: at, message: "an event's data puts no string under a credential's name" });
+    else if (secretValue(member) || secretUrl(member)) findings.push({ code: 'FAC-SEM-101', instancePath: at, message: "an event's data carries no value shaped like a credential" });
+  };
+  (Array.isArray(page?.events) ? page.events : []).forEach((event, i) => {
+    if (!isPlain(event) || !isPlain(event.data) || !isPlain(event.data.value)) return;
+    for (const [key, member] of Object.entries(event.data.value)) {
+      const at = `/events/${i}/data/value/${pointerToken(key)}`;
+      const named = credentialName(key);
+      check(named, member, at);
+      if (Array.isArray(member)) member.forEach((item, j) => check(named, item, `${at}/${j}`));
+      else if (isPlain(member)) for (const [inner, leaf] of Object.entries(member)) check(named || credentialName(inner), leaf, `${at}/${pointerToken(inner)}`);
+    }
+  });
+  return findings;
+}
+
+/** DEC-0070's `data {schema, value}` as the schema bounds it, then FAC-SEM-101. */
+export function feedDataProblems(data) {
+  if (!isPlain(data) || Object.keys(data).length !== 2 || !('schema' in data) || !('value' in data)) return ['data is {schema, value}'];
+  const problems = [];
+  if (!(typeof data.schema === 'string' && SCHEMA_URI.test(data.schema))) problems.push('data.schema is the absolute URI of a payload schema the service publishes');
+  const value = data.value;
+  if (!isPlain(value) || Object.keys(value).length > 32) return [...problems, 'data.value is an object of at most 32 members'];
+  for (const [key, member] of Object.entries(value)) {
+    if (scalar(member)) continue;
+    if (Array.isArray(member) && member.length <= 32 && member.every(scalar)) continue;
+    if (isPlain(member) && Object.keys(member).length <= 32 && Object.values(member).every(scalar)) continue;
+    problems.push(`data.value.${key} is a scalar (a string of at most 500 characters), a list of at most 32 scalars or an object of at most 32 scalar members`);
+  }
+  if (problems.length) return problems;
+  return feedDataFindings({ events: [{ data }] }).map((f) => `FAC-SEM-101: ${f.instancePath.replace('/events/0', '')} ${f.message}`);
+}
+
+/** One activity event. `data` (DEC-0070) adds machine-readable fields, `{schema, value}`, never a secret: refused here, so no feed carries one. */
+export function makeEvent(id, at, kind, level, text, { subject, link, notify, traceId, spanId, data } = {}) {
   if (!LEVELS.includes(level)) throw new ServiceError(`level must be one of ${LEVELS.join(', ')}.`);
   if (!KIND.test(kind)) throw new ServiceError(`kind ${kind} must be dotted lowercase.`);
   const sentence = String(text).split(/\s+/).filter(Boolean).join(' ');
@@ -862,6 +982,11 @@ export function makeEvent(id, at, kind, level, text, { subject, link, notify, tr
   if (link) event.link = link;
   if (notify) event.notify = true;
   if (traceId !== undefined) Object.assign(event, { traceId, spanId });
+  if (data !== undefined) {
+    const problems = feedDataProblems(data);
+    if (problems.length) throw new ServiceError(`Event data: ${problems.join('; ')}.`);
+    event.data = { schema: data.schema, value: data.value };
+  }
   return event;
 }
 

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

@@ -826,15 +826,21 @@ def _secret_references(value: Dict[str, Any], flag) -> None:
             slots.append(key)
 
 
+def _grant_key(ident: Any) -> Any:
+    """A grant's id is a URI, so grants and their revocations are keyed by its normal form (DEC-0076)."""
+    import fabric_identifiers  # noqa: E402 - beside this file
+    return fabric_identifiers.normal_identifier(ident) if isinstance(ident, str) else ident
+
+
 def _grants_and_revocations(value: Dict[str, Any], flag) -> None:
     grant_ids: List[Any] = []
     for index, grant in enumerate(_list(_get(value, "shareGrants"))):
         if _get(grant, "principalKind") != "external":
             flag("/shareGrants/%d/principalKind" % index, "a share grant is to a principal outside the estate: principalKind external")
         ident = _get(_get(grant, "meta"), "id") if isinstance(_get(grant, "meta"), dict) else _MISSING
-        if _contains(grant_ids, ident):
+        if _contains(grant_ids, _grant_key(ident)):
             flag("/shareGrants/%d/meta/id" % index, "grant %s is listed twice" % _js_string(ident))
-        grant_ids.append(ident)
+        grant_ids.append(_grant_key(ident))
     machines = _list(_get(value, "machines"))
     listed = {
         "authority": [_get(e, "credentialId") for e in _list(_get(value, "authorities"))],
@@ -847,11 +853,12 @@ def _grants_and_revocations(value: Dict[str, Any], flag) -> None:
     }
     seen: List[str] = []
     for index, revocation in enumerate(_list(_get(value, "revocations"))):
-        key = "%s %s" % (_s(revocation, "kind"), _s(revocation, "ref"))
+        ref = _grant_key(_get(revocation, "ref")) if _get(revocation, "kind") == "grant" else _get(revocation, "ref")
+        key = "%s %s" % (_s(revocation, "kind"), _js_string(ref))
         if key in seen:
             flag("/revocations/%d" % index, "the %s %s is revoked twice" % (_s(revocation, "kind"), _s(revocation, "ref")))
         seen.append(key)
-        if _contains(listed.get(_s(revocation, "kind"), []), _get(revocation, "ref")):
+        if _contains(listed.get(_s(revocation, "kind"), []), ref):
             flag("/revocations/%d/ref" % index, "the record still lists the %s it revokes: revocation outranks addition" % _s(revocation, "kind"))
 
 

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

@@ -0,0 +1,182 @@
+"""Identifier equality (contract DEC-0076): two identifiers are the same when their normal forms are equal.
+
+A port of the contract's `src/identifiers.ts`, held to its `fixtures/vectors/identifiers.json`. The normal form of a URI
+is RFC 3986 §6.2.2 syntax-based normalization: the scheme and the host lower-cased and percent-encoding hex upper-cased
+(§6.2.2.1), percent-encoded unreserved characters decoded (§6.2.2.2), dot segments removed from a hierarchical path
+(§6.2.2.3), and only the leading ones from a rootless path; nothing scheme-based (§6.2.3). A `urn:` URI follows RFC 8141
+§3.1 instead: the scheme and the NID lower-cased, percent-encoding hex upper-cased, nothing decoded, the NSS's case kept,
+the r-, q- and f-components ignored. A string that is not a URI by RFC 3986's `URI` production is its own normal form.
+Nothing here raises. Standard library only; this file is byte-identical in both skills' `scripts/`."""
+from __future__ import annotations
+
+import re
+from typing import Any, Optional, Tuple
+
+_UNRESERVED = r"A-Za-z0-9\-._~"
+_SUB_DELIMS = r"!$&'()*+,;="
+_PCT = r"%[0-9A-Fa-f]{2}"
+
+
+def _run(chars: str) -> "re.Pattern[str]":
+    """`*( <chars> / pct-encoded )`, linear: one character class beside one fixed triplet."""
+    return re.compile(r"(?:[%s]|%s)*" % (chars, _PCT), re.ASCII)
+
+
+_USERINFO = _run(_UNRESERVED + _SUB_DELIMS + ":")
+_REG_NAME = _run(_UNRESERVED + _SUB_DELIMS)
+_PATH = _run(_UNRESERVED + _SUB_DELIMS + ":@/")
+_QUERY = _run(_UNRESERVED + _SUB_DELIMS + ":@/?")
+_PORT = re.compile(r"[0-9]*", re.ASCII)
+_SCHEME = re.compile(r"[A-Za-z][A-Za-z0-9+.-]*", re.ASCII)
+
+# RFC 3986 §3.2.2: IP-literal = "[" ( IPv6address / IPvFuture ) "]".
+_H16 = "[0-9A-Fa-f]{1,4}"
+_DEC_OCTET = "(?:25[0-5]|2[0-4][0-9]|1[0-9]{2}|[1-9]?[0-9])"
+_IPV4 = r"%s(?:\.%s){3}" % (_DEC_OCTET, _DEC_OCTET)
+_LS32 = "(?:%s:%s|%s)" % (_H16, _H16, _IPV4)
+_IPV6 = "|".join([
+    "(?:%s:){6}%s" % (_H16, _LS32),
+    "::(?:%s:){5}%s" % (_H16, _LS32),
+    "(?:%s)?::(?:%s:){4}%s" % (_H16, _H16, _LS32),
+    "(?:(?:%s:){0,1}%s)?::(?:%s:){3}%s" % (_H16, _H16, _H16, _LS32),
+    "(?:(?:%s:){0,2}%s)?::(?:%s:){2}%s" % (_H16, _H16, _H16, _LS32),
+    "(?:(?:%s:){0,3}%s)?::%s:%s" % (_H16, _H16, _H16, _LS32),
+    "(?:(?:%s:){0,4}%s)?::%s" % (_H16, _H16, _LS32),
+    "(?:(?:%s:){0,5}%s)?::%s" % (_H16, _H16, _H16),
+    "(?:(?:%s:){0,6}%s)?::" % (_H16, _H16),
+])
+_IP_LITERAL = re.compile(r"\[(?:%s|[Vv][0-9A-Fa-f]+\.[%s%s:]+)\]" % (_IPV6, _UNRESERVED, _SUB_DELIMS), re.ASCII)
+
+# RFC 8141 §2: NID = (alphanum) 0*30(ldh) (alphanum), then ":" and a non-empty NSS.
+_URN_NAME = re.compile(r"([A-Za-z0-9][A-Za-z0-9-]{0,30}[A-Za-z0-9]):(.+)", re.ASCII | re.DOTALL)
+_SPLIT = re.compile(r"([^:/?#]+):(?://([^/?#]*))?([^?#]*)(?:\?([^#]*))?(?:#(.*))?", re.DOTALL)
+_TRIPLET = re.compile(r"%([0-9A-Fa-f]{2})")
+_UNRESERVED_CHAR = re.compile(r"[A-Za-z0-9\-._~]", re.ASCII)
+
+
+def _percent(text: str, keep_encoded: bool = False) -> str:
+    """Percent-encoding hex upper-cased (§6.2.2.1), and unreserved characters decoded unless ``keep_encoded``."""
+    def one(match: "re.Match[str]") -> str:
+        char = chr(int(match.group(1), 16))
+        return char if not keep_encoded and _UNRESERVED_CHAR.fullmatch(char) else "%" + match.group(1).upper()
+    return _TRIPLET.sub(one, text)
+
+
+def _strip_leading_dots(path: str) -> str:
+    """A rootless path loses its leading "./" and "../" segments while what is left stays rootless (DEC-0076)."""
+    start = 0
+    while path.startswith("./", start) or path.startswith("../", start):
+        start += 2 if path.startswith("./", start) else 3
+    rest = path[start:]
+    return path if rest == "" or rest.startswith("/") else rest
+
+
+def _remove_dot_segments(path: str) -> str:
+    """RFC 3986 §5.2.4 remove_dot_segments over a path whose "." and ".." are already decoded."""
+    absolute = path.startswith("/")
+    segments = (path[1:] if absolute else path).split("/")
+    output = []
+    for index, segment in enumerate(segments):
+        last = index == len(segments) - 1
+        if segment in (".", ".."):
+            if segment == ".." and output:
+                output.pop()
+            if last:  # a dot segment that ends the path leaves it ending in "/"
+                output.append("")
+            continue
+        output.append(segment)
+    return ("/" if absolute else "") + "/".join(output)
+
+
+def _authority_parts(authority: str) -> Optional[Tuple[Optional[str], str, Optional[str]]]:
+    at = authority.rfind("@")
+    userinfo = None if at == -1 else authority[:at]
+    host_port = authority if at == -1 else authority[at + 1:]
+    bracket = host_port.find("]") if host_port.startswith("[") else -1
+    colon = host_port.find(":", 0 if bracket == -1 else bracket)
+    host = host_port if colon == -1 else host_port[:colon]
+    port = None if colon == -1 else host_port[colon + 1:]
+    if userinfo is not None and not _USERINFO.fullmatch(userinfo):
+        return None
+    if port is not None and not _PORT.fullmatch(port):
+        return None
+    if not (_IP_LITERAL.fullmatch(host) if host.startswith("[") else _REG_NAME.fullmatch(host)):
+        return None
+    return userinfo, host, port
+
+
+def _parse(text: str) -> Optional[Tuple[str, Optional[str], str, Optional[str], Optional[str]]]:
+    """RFC 3986 Appendix B's split, then each component checked against its §3 production; None when one fails."""
+    match = _SPLIT.fullmatch(text)
+    if not match:
+        return None
+    scheme, authority, path, query, fragment = match.groups()
+    path = path or ""
+    if not _SCHEME.fullmatch(scheme) or not _PATH.fullmatch(path):
+        return None
+    if query is not None and not _QUERY.fullmatch(query):
+        return None
+    if fragment is not None and not _QUERY.fullmatch(fragment):
+        return None
+    if authority is not None and _authority_parts(authority) is None:
+        return None
+    if authority is None and path == "":
+        return None
+    return scheme, authority, path, query, fragment
+
+
+def _urn_form(authority: Optional[str], path: str, query: Optional[str]) -> str:
+    name = _URN_NAME.fullmatch(path)
+    path = "%s:%s" % (name.group(1).lower(), _percent(name.group(2), True)) if name else _percent(path, True)
+    # A "?" not followed by "+" or "=" is no URN component (RFC 8141 §2): it is kept, never dropped unread.
+    kept = "?" + _percent(query, True) if query is not None and not re.match(r"[+=]", query) else ""
+    auth = "//" + _percent(authority, True) if authority is not None else ""
+    return "urn:%s%s%s" % (auth, path, kept)
+
+
+def _generic_form(scheme: str, authority: Optional[str], path: str, query: Optional[str], fragment: Optional[str]) -> str:
+    auth = ""
+    if authority is not None:
+        userinfo, host, port = _authority_parts(authority)  # type: ignore[misc]
+        # The host is case-insensitive (§3.2.2); its remaining percent triplets keep upper-case hex.
+        lowered = re.sub(r"%[0-9a-f]{2}", lambda m: m.group(0).upper(), _percent(host).lower())
+        auth = "//%s%s%s" % ("" if userinfo is None else _percent(userinfo) + "@", lowered, "" if port is None else ":" + port)
+    decoded = _percent(path)
+    hierarchical = authority is not None or decoded.startswith("/")
+    out = _remove_dot_segments(decoded) if hierarchical else _strip_leading_dots(decoded)
+    if authority is None and out.startswith("//"):  # it would read as an authority: keep the decoded path
+        out = decoded
+    q = "" if query is None else "?" + _percent(query)
+    f = "" if fragment is None else "#" + _percent(fragment)
+    return "%s:%s%s%s%s" % (scheme.lower(), auth, out, q, f)
+
+
+def normal_identifier(value: Any) -> Optional[str]:
+    """The normal form of an identifier: a URI's syntax-normalized form (RFC 3986 §6.2.2; RFC 8141 §3.1 for `urn:`),
+    any other string as it is, None for a value that is not a string. The contract's `normalIdentifier`."""
+    if not isinstance(value, str):
+        return None
+    parts = _parse(value)
+    if parts is None:
+        return value
+    scheme, authority, path, query, fragment = parts
+    return _urn_form(authority, path, query) if scheme.lower() == "urn" else _generic_form(scheme, authority, path, query, fragment)
+
+
+def _strict_equal(a: Any, b: Any) -> bool:
+    """JavaScript's === on parsed JSON: numbers by value, booleans only with booleans, objects by identity."""
+    if isinstance(a, bool) or isinstance(b, bool):
+        return isinstance(a, bool) and isinstance(b, bool) and a == b
+    if isinstance(a, (int, float)) and isinstance(b, (int, float)):
+        return a == b
+    if isinstance(a, (dict, list)) or isinstance(b, (dict, list)):
+        return a is b
+    return type(a) is type(b) and a == b
+
+
+def same_identifier(a: Any, b: Any) -> bool:
+    """Two identifiers are the same when their normal forms are equal (DEC-0076). A value that is not a string is no
+    identifier and is compared as it is (JavaScript's ===). The contract's `sameIdentifier`."""
+    if not isinstance(a, str) or not isinstance(b, str):
+        return _strict_equal(a, b)
+    return normal_identifier(a) == normal_identifier(b)