@passioncode-ai/fabric-agent-adapter 0.14.0 → 0.16.0

package/plugins/fabric-agent-adapter/skills/building-fabric-services/references/protocol.md

@@ -63,7 +63,7 @@ No auth; the Host/Origin guard applies; answered from memory in under 100 ms.
   entries through unchanged.
 - `configuration` (DEC-0046) MAY say which runner and model profile the service resolved and from where
   (`request`, `agent`, `binding`, `estate`); a usage receipt MAY carry the `route` (`subscription` or `key`). The kits
-  do not emit either yet (FAA-19).
+  build both: `fabric_profiles.configuration` and `make_usage_receipt(route=)` ([profiles](profiles.md)).
 - `build` needs `commit` or `digest` (`sha256:<64 hex>`).
 - `summary`: at most six tiles; `attention: true` counts toward the host's badge.
 - `surfaces.events` is required; `dashboard` and `mcp` when the service has them; `usage`

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

@@ -245,6 +245,7 @@ class Probe:
         if "events" not in (wk.get("surfaces") or {}):
             problems.append("surfaces.events missing")
         self.add("well-known.shape", "FAIL" if problems else "PASS", "; ".join(problems) or "protocol, build, status, degraded, surfaces")
+        self.configuration_rule()
         svc = wk.get("service") or {}
         answered = "%s.%s" % (svc.get("id"), svc.get("instance"))
         expected = "%s.%s" % (self.d.get("id"), self.d.get("instance", "default"))
@@ -524,6 +525,16 @@ class Probe:
                 self.trace_rule(listing, sent)
         self.events_trace_rule(self.events)
 
+    def configuration_rule(self) -> None:
+        """DEC-0046: a well-known `configuration` is {slots, resolved} as the schema types it; absent is NOT_RUN."""
+        if not isinstance(self.wk, dict) or "configuration" not in self.wk:
+            self.add("configuration.declared", "NOT_RUN", "the service declares no runner or model configuration")
+            return
+        problems = fs.configuration_problems(self.wk["configuration"])
+        self.add("configuration.declared", "FAIL" if problems else "PASS", "; ".join(problems) or
+                 "slots %s; resolved from %s" % (", ".join(self.wk["configuration"].get("slots") or []) or "none",
+                                                 (self.wk["configuration"].get("resolved") or {}).get("from", "not stated")))
+
     def delegation_declared_rule(self, mcp_surface: Optional[Dict[str, Any]]) -> None:
         """DL-16 (DEC-0039): a service that accepts delegation tokens names the issuer it trusts and its JWKS
         in auth.delegation; with surfaces.mcp.auth delegation that declaration is required."""

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

@@ -27,7 +27,7 @@ from typing import Any, Dict, List, Optional, Sequence, Tuple
 
 KIT_DIR = Path(__file__).resolve().parent.parent / "assets" / "dashboard-kit"
 KIT_NAME = "fabric-dashboard-kit"
-COPIED = ("fabric-dashboard.css", "fabric-dashboard.js")
+COPIED = ("fabric-dashboard.css", "fabric-dashboard.js", "fabric-button.js")  # fabric-button.js: DEC-0040, FB-7
 MARKER = re.compile(r"fabric-dashboard-kit@(\d+)\.(\d+)\.(\d+)(?:-[0-9A-Za-z.-]+)?")
 CSS_BEGIN, CSS_END = "/* fabric-dashboard-kit:themes:begin */", "/* fabric-dashboard-kit:themes:end */"
 JS_BEGIN, JS_END = "/* fabric-dashboard-kit:theme-ids:begin */", "/* fabric-dashboard-kit:theme-ids:end */"
@@ -125,7 +125,10 @@ def build(kit_dir: Path = KIT_DIR, check: bool = False) -> List[str]:
     new_js = replace_between(js, JS_BEGIN, JS_END, "  var THEMES = %s;" % json.dumps(ids).replace('"', "'"), js_path.name)
     manifest = load_manifest(kit_dir)
     version = manifest["version"]
-    for text, name in ((new_css, css_path.name), (new_js, js_path.name)):
+    built = {css_path.name: new_css, js_path.name: new_js}
+    for name in COPIED:
+        built.setdefault(name, (kit_dir / name).read_text(encoding="utf-8"))
+    for name, text in built.items():
         if claimed_version_text(text) != version:
             raise KitError("%s says %s, kit.json says %s; raise them together." % (name, claimed_version_text(text), version))
     import hashlib
@@ -135,7 +138,7 @@ def build(kit_dir: Path = KIT_DIR, check: bool = False) -> List[str]:
             changed.append(path.name)
             if not check:
                 atomic_write(path, text)
-    digest = {name: hashlib.sha256((new_css if name.endswith(".css") else new_js).encode("utf-8")).hexdigest() for name in COPIED}
+    digest = {name: hashlib.sha256(built[name].encode("utf-8")).hexdigest() for name in COPIED}
     digest["themes.json"] = sha256(kit_dir / "themes.json")
     new_manifest = dict(manifest)
     new_manifest["themes"] = ids
@@ -199,7 +202,7 @@ def repo_root(start: Path) -> Optional[Path]:
 
 def find_copies(repo: Path) -> List[Path]:
     listed = git(repo, "ls-files", "-z", "--cached", "--others", "--exclude-standard", "--",
-                 "*fabric-dashboard.css", "*fabric-dashboard.js")
+                 "*fabric-dashboard.css", "*fabric-dashboard.js", "*fabric-button.js")
     if listed is not None:
         paths = [repo / p for p in listed.split("\0") if p]
     else:

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

@@ -0,0 +1,196 @@
+// Runner and model profiles in the kit (Fabric Agent Contract DEC-0046, Fabric ADR-0147). A port of the contract's
+// `src/profile-rules.ts` at the pin — resolveModelProfile and the FAC-SEM-058…060 checks — held to the contract's own
+// answers by test/fixtures/contract/profile-vectors.json; plus the doctor's runner and model checks (runners.md C2) and
+// the well-known `configuration` with its summary tiles ("Runner & model"). No dependencies.
+
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { secretValue } from './fabric-secrets.mjs';
+import { configurationProblems } from './fabric-service.mjs';
+
+export const RESOLUTION_ORDER = Object.freeze(['request', 'agent', 'binding', 'estate']);
+/** The vendor login each subscription is, and the one runner kind it runs in (DEC-0046, ADR-0147 decision 2). */
+export const SUBSCRIPTION_RUNNER = Object.freeze({ claude: 'claude-code', kimi: 'kimi-code', chatgpt: 'codex' });
+export const MAX_PROBE_MS = 5000;
+const BARE_BINARY = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+
+export class ProfileError extends Error {}
+
+const isObject = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const list = (value) => (Array.isArray(value) ? value.filter(isObject) : []);
+const strings = (value) => (Array.isArray(value) ? value.filter((item) => typeof item === 'string') : []);
+const jsonEqual = (a, b) => JSON.stringify(sortKeys(a)) === JSON.stringify(sortKeys(b));
+function sortKeys(value) {
+  if (Array.isArray(value)) return value.map(sortKeys);
+  if (isObject(value)) return Object.fromEntries(Object.keys(value).sort().map((k) => [k, sortKeys(value[k])]));
+  return value;
+}
+
+/** FAC-SEM-060: the request's profile, else the agent's, else the binding's or project's, else the estate default. */
+export function resolveModelProfile({ catalogue, profiles, choices = {}, policy } = {}) {
+  const level = RESOLUTION_ORDER.find((name) => typeof choices?.[name] === 'string');
+  if (level === undefined) return { refused: 'no-profile' };
+  const id = choices[level];
+  const profile = list(profiles).find((item) => item.id === id);
+  if (!profile) return { refused: 'unknown-profile', profile: id };
+  const models = strings(profile.models);
+  if (!isObject(policy) || !Array.isArray(policy.modelClasses)) return { from: level, profile: id, models };
+  const allowed = new Set(strings(policy.modelClasses));
+  const rows = new Map(list(isObject(catalogue) ? catalogue.models : undefined).map((row) => [row.id, row]));
+  const within = models.filter((model) => { const row = rows.get(model); return row !== undefined && strings(row.classes).every((name) => allowed.has(name)); });
+  if (within.length) return { from: level, profile: id, models: within };
+  const meta = isObject(policy.meta) ? policy.meta : {};
+  return { refused: 'model-classes-empty', profile: id, policy: { id: String(meta.id), revision: Number(meta.revision) } };
+}
+
+const finding = (code, instancePath, message) => ({ code, instancePath, message });
+
+function modelCatalogue(value) {
+  const findings = [];
+  const seen = new Set();
+  list(value.models).forEach((row, index) => {
+    if (seen.has(row.id)) findings.push(finding('FAC-SEM-058', `/models/${index}/id`, `model ${String(row.id)} is catalogued more than once`));
+    seen.add(row.id);
+    const routing = isObject(row.provider) ? row.provider : {};
+    const ignored = new Set(strings(routing.ignore));
+    for (const slug of strings(routing.order)) {
+      if (ignored.has(slug) || ignored.has(slug.split('/')[0])) findings.push(finding('FAC-SEM-058', `/models/${index}/provider`, `model ${String(row.id)} both orders and ignores provider ${slug}`));
+    }
+  });
+  return findings;
+}
+
+function modelProfiles(value) {
+  const findings = [];
+  const seen = new Set();
+  list(value.profiles).forEach((profile, index) => {
+    if (seen.has(profile.id)) findings.push(finding('FAC-SEM-058', `/profiles/${index}/id`, `model profile ${String(profile.id)} is declared more than once`));
+    seen.add(profile.id);
+  });
+  return findings;
+}
+
+function runnerProfile(value) {
+  const findings = [];
+  if (value.route === 'subscription' && isObject(value.subscription)) {
+    const login = String(value.subscription.login);
+    const runner = Object.hasOwn(SUBSCRIPTION_RUNNER, login) ? SUBSCRIPTION_RUNNER[login] : undefined;
+    if (runner !== value.runnerKind) findings.push(finding('FAC-SEM-059', '/runnerKind', `a ${login} subscription runs only in ${runner ?? "its vendor's runner"}, not in ${String(value.runnerKind)}; another runner takes the key route`));
+  }
+  if (value.route === 'key' && isObject(value.key)) {
+    if (value.key.modelAllowList !== value.modelProfile) findings.push(finding('FAC-SEM-059', '/key/modelAllowList', `the key admits the models of ${String(value.key.modelAllowList)}, but the profile runs ${String(value.modelProfile)}`));
+    if (typeof value.key.ref === 'string' && secretValue(value.key.ref)) findings.push(finding('FAC-SEM-059', '/key/ref', 'the key is named by its secret reference, never by its value'));
+  }
+  return findings;
+}
+
+function profileResolution(value) {
+  const findings = [];
+  const catalogued = new Set(list(isObject(value.catalogue) ? value.catalogue.models : undefined).map((row) => row.id));
+  const ids = new Set();
+  list(value.profiles).forEach((profile, i) => {
+    if (ids.has(profile.id)) findings.push(finding('FAC-SEM-060', `/profiles/${i}/id`, `profile id ${String(profile.id)} is offered more than once to one resolution`));
+    ids.add(profile.id);
+    strings(profile.models).forEach((model, j) => {
+      if (!catalogued.has(model)) findings.push(finding('FAC-SEM-060', `/profiles/${i}/models/${j}`, `profile ${String(profile.id)} names ${model}, which the catalogue does not hold`));
+    });
+  });
+  const choices = isObject(value.choices) ? value.choices : {};
+  const expected = resolveModelProfile({ catalogue: value.catalogue, profiles: value.profiles, choices, policy: value.policy });
+  if (value.resolved === undefined || !jsonEqual(value.resolved, expected)) findings.push(finding('FAC-SEM-060', '/resolved', `the resolution is ${JSON.stringify(expected)}`));
+  return findings;
+}
+
+/** The contract's profileRules: findings for a model-catalogue, model-profiles, runner-profile or profile-resolution; else undefined. */
+export function profileProblems(kind, value) {
+  return { 'model-catalogue': modelCatalogue, 'model-profiles': modelProfiles, 'runner-profile': runnerProfile, 'profile-resolution': profileResolution }[kind]?.(value);
+}
+
+// ---- the doctor's checks ----
+
+const argvOf = (value, label) => {
+  if (!Array.isArray(value) || !value.every((a) => typeof a === 'string')) throw new ProfileError(`${label} is an argument array, never a shell string`);
+  return [...value];
+};
+
+function which(name, searchPath) {
+  for (const dir of String(searchPath ?? '').split(path.delimiter).filter(Boolean)) {
+    const candidate = path.join(dir, name);
+    try { fs.accessSync(candidate, fs.constants.X_OK); if (fs.statSync(candidate).isFile()) return candidate; } catch { /* next */ }
+  }
+  return null;
+}
+
+/**
+ * runners.md C2: is the catalogued runner installed, which version answers, and is it signed in. Only a bare
+ * catalogued binary on PATH is run, only with the catalogued version (and auth) argv, without a shell, within its
+ * timeout (at most 5 s). An entry outside these rules is refused and nothing runs.
+ */
+export function runnerCheck(entry, { searchPath = process.env.PATH, run = spawnSync } = {}) {
+  const { kind, binaries } = entry ?? {};
+  if (!Array.isArray(binaries) || !binaries.length || !binaries.every((b) => typeof b === 'string' && BARE_BINARY.test(b) && !b.includes('..'))) throw new ProfileError('binaries are bare executable names, never paths');
+  const version = isObject(entry.version) ? entry.version : {};
+  const versionArgv = argvOf(version.argv, 'version.argv');
+  if (typeof version.pattern !== 'string') throw new ProfileError('version.pattern is a regular expression');
+  const timeoutMs = version.timeoutMs ?? MAX_PROBE_MS;
+  if (!Number.isInteger(timeoutMs) || timeoutMs <= 0 || timeoutMs > MAX_PROBE_MS) throw new ProfileError(`version.timeoutMs is at most ${MAX_PROBE_MS}`);
+  const authArgv = 'auth' in entry ? argvOf(entry.auth, 'auth') : null;
+  const out = { kind, installed: false, binary: null, version: null, signedIn: null, problems: [] };
+  const binary = binaries.map((name) => which(name, searchPath)).find(Boolean) ?? null;
+  if (!binary) { out.problems.push(`${kind} is not installed: none of ${binaries.join(', ')} is on PATH`); return out; }
+  Object.assign(out, { installed: true, binary });
+  const probe = (argv) => {
+    const result = run(binary, argv, { encoding: 'utf8', timeout: timeoutMs, shell: false });
+    if (result.error?.code === 'ETIMEDOUT' || result.signal === 'SIGTERM') { out.problems.push(`${kind} ${argv.join(' ')} did not answer within ${timeoutMs} ms`); return null; }
+    if (result.error) { out.problems.push(`${kind} could not be run: ${result.error.code ?? result.error.name}`); return null; }
+    return result;
+  };
+  const answered = probe(versionArgv);
+  if (answered) {
+    const re = new RegExp(version.pattern);
+    const match = re.exec(answered.stdout ?? '') ?? re.exec(answered.stderr ?? '');
+    if (match && match.length > 1) out.version = match[1];
+    else out.problems.push(`${kind} answered, but its version did not match the catalogue's pattern`);
+  }
+  if (authArgv) {
+    const signed = probe(authArgv);
+    if (signed) { out.signedIn = signed.status === 0; if (!out.signedIn) out.problems.push(`${kind} is installed but not signed in`); }
+  }
+  return out;
+}
+
+/** Problems with running `model` here: not in the catalogue, or a class the project's policy does not allow. */
+export function modelUsable(model, catalogue, policy) {
+  const rows = new Map(list(isObject(catalogue) ? catalogue.models : undefined).map((row) => [row.id, row]));
+  if (!rows.has(model)) return [`model ${model} is not in the model catalogue`];
+  if (isObject(policy) && Array.isArray(policy.modelClasses)) {
+    const allowed = new Set(strings(policy.modelClasses));
+    const outside = strings(rows.get(model).classes).filter((c) => !allowed.has(c));
+    if (outside.length) return [`model ${model} has class ${outside.join(', ')}, which policy ${String((isObject(policy.meta) ? policy.meta : {}).id)} does not allow`];
+  }
+  return [];
+}
+
+// ---- the well-known `configuration` and its tiles ----
+
+/** The well-known `configuration` (DEC-0046): read-only; a change is made in Fabric and reaches the agent through its binding. */
+export function configuration(slots, resolution, runnerProfileDoc) {
+  if ('refused' in resolution) throw new ProfileError(`the resolution was refused (${resolution.refused}); a refused resolution is not a configuration`);
+  const resolved = { from: resolution.from };
+  if (runnerProfileDoc) Object.assign(resolved, { runnerProfile: runnerProfileDoc.id, runnerKind: runnerProfileDoc.runnerKind, route: runnerProfileDoc.route });
+  Object.assign(resolved, { modelProfile: resolution.profile, models: [...(resolution.models ?? [])] });
+  const doc = { slots: [...slots], resolved: Object.fromEntries(Object.entries(resolved).filter(([, v]) => v !== undefined && v !== null)) };
+  const problems = configurationProblems(doc);
+  if (problems.length) throw new ProfileError(problems.join('; '));
+  return doc;
+}
+
+/** Summary tiles for the well-known document and the dashboard — "Runner & model". */
+export function configurationSummary(doc) {
+  const resolved = doc?.resolved ?? {};
+  const tiles = [];
+  if (resolved.runnerKind) tiles.push({ label: 'Runner', value: [resolved.runnerKind, resolved.route].filter(Boolean).join(' · ') });
+  if (resolved.modelProfile) tiles.push({ label: 'Model', value: [resolved.modelProfile, (resolved.models ?? [])[0]].filter(Boolean).join(' · ') });
+  return tiles;
+}

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

@@ -0,0 +1,86 @@
+// The contract's one credential detector (Fabric Agent Contract DEC-0044, `src/secret-shape.ts` at the pin): a name
+// that can only carry a credential, a value shaped like one, a launch argument that carries one, and a URL that does
+// (LC-21). A port held to the contract's own answers by test/fixtures/contract/profile-vectors.json. No dependencies.
+
+/** A name's words: split at `.`, `_`, `-` and camelCase humps, lowercased (`APIKey` is `api key`). */
+export function nameWords(name) {
+  return name
+    .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+    .replace(/([A-Z]+)([A-Z][a-z])/g, '$1 $2')
+    .split(/[\s._-]+/)
+    .filter(Boolean)
+    .map((word) => word.toLowerCase());
+}
+
+export const CREDENTIAL_WORDS = Object.freeze([
+  'token', 'secret', 'password', 'passwd', 'pass', 'passphrase', 'credential', 'credentials', 'cookie', 'authorization',
+  'bearer', 'jwt', 'otp', 'apikey', 'signature', 'sig',
+  'accesstoken', 'idtoken', 'authtoken', 'refreshtoken', 'sessionid', 'sessiontoken', 'logincode', 'authcode', 'privatekey',
+  'clientsecret', 'secretkey', 'accesskey',
+]);
+export const CREDENTIAL_PAIRS = Object.freeze({
+  key: ['private', 'api', 'access', 'secret', 'session', 'auth', 'signing', 'encryption', 'master', 'client', 'login', 'refresh'],
+  auth: ['token', 'code', 'header'],
+  session: ['token', 'id'],
+  code: ['login', 'auth', 'access', 'session'],
+});
+
+const withSingulars = (words) => [...words, ...words.filter((word) => word.length > 2 && word.endsWith('s')).map((word) => word.slice(0, -1))];
+
+/** Whether a name — a parameter, a header, an environment variable, a config key — can only carry a credential. */
+export function credentialName(name) {
+  const split = nameWords(name);
+  const words = withSingulars(split);
+  if (words.some((word) => CREDENTIAL_WORDS.includes(word))) return true;
+  if (split.length === 1 && words.some((word) => Object.hasOwn(CREDENTIAL_PAIRS, word))) return true;
+  return Object.entries(CREDENTIAL_PAIRS).some(([word, partners]) => words.includes(word) && partners.some((partner) => words.includes(partner)));
+}
+
+/** A JWT or JWS anywhere in a value. */
+export const JWT_SHAPE = /eyJ[A-Za-z0-9_-]{2,}\.[A-Za-z0-9_-]{2,}\.[A-Za-z0-9_-]*/;
+/** A value that says it is a credential, or a provider key's shape. */
+export const SECRET_VALUE = /(^bearer\s.+|sk-[A-Za-z0-9_-]{16,}|gh[pousr]_[A-Za-z0-9]{20,}|xox[abposr]-[A-Za-z0-9-]{10,}|AKIA[0-9A-Z]{16}|glpat-[A-Za-z0-9_-]{20,})/i;
+const LONG_RUN = /[A-Za-z0-9+/=_-]{40,}/g;
+const longSecret = (value) => (value.match(LONG_RUN) ?? []).some((run) => /[a-z]/.test(run) && /[A-Z]/.test(run) && /[0-9]/.test(run));
+
+/** Whether a value could be a credential: a JWT anywhere, a provider key or `Bearer …`, or a long secret-shaped run. */
+export const secretValue = (value) => JWT_SHAPE.test(value) || SECRET_VALUE.test(value) || longSecret(value);
+
+const BEARER_INSIDE = /\bbearer\s+(?=[A-Za-z0-9._~+/-]*\d)[A-Za-z0-9._~+/-]{12,}=*/i;
+const PATH_LIKE = /^(?:[/~.]|[A-Za-z]:[\\/]|[a-z][a-z0-9+.-]*:\/\/)/i;
+const pathLike = (piece) =>
+  PATH_LIKE.test(piece) ||
+  (/[\\/]/.test(piece) && (/\.[A-Za-z0-9]{1,8}$/.test(piece) || piece.split(/[\\/]/).some((segment) => /^[a-z][a-z0-9_-]{2,}$/.test(segment))));
+
+/** The same for a launch argument or a server's command and URL: a long run is looked for between path separators. */
+export const secretArgument = (value) =>
+  JWT_SHAPE.test(value) || SECRET_VALUE.test(value) || BEARER_INSIDE.test(value) ||
+  value.split(/[\s=]/).some((piece) => (pathLike(piece) ? piece.split(/[\\/]/).some((part) => longSecret(part)) : longSecret(piece)));
+
+const decodeKeepingPlus = (raw) => { try { return decodeURIComponent(raw); } catch { return raw; } };
+
+/** Each query or fragment piece's raw value by its decoded name, with `+` kept. */
+export function rawValues(query) {
+  const values = new Map();
+  for (const piece of query.split('&')) {
+    if (piece === '') continue;
+    const at = piece.indexOf('=');
+    const name = [...new URLSearchParams(at < 0 ? piece : piece.slice(0, at)).keys()][0] ?? '';
+    values.set(name, [...(values.get(name) ?? []), at < 0 ? '' : decodeKeepingPlus(piece.slice(at + 1))]);
+  }
+  return values;
+}
+
+/** Whether a URL an MCP entry or a launch names carries a credential (LC-21). */
+export function secretUrl(value) {
+  if (secretArgument(value)) return true;
+  let url;
+  try { url = new URL(value); } catch { return false; }
+  if (url.password !== '') return true;
+  for (const part of [url.search, url.hash]) {
+    for (const [name, values] of rawValues(part.slice(1))) {
+      if (values.some((raw) => (raw !== '' && credentialName(name)) || secretValue(raw))) return true;
+    }
+  }
+  return false;
+}

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

@@ -14,7 +14,7 @@ export const EXTENSION_KEY = 'https://fabric.passioncode.ai/agent-contract/exten
 // The embedded dashboard declaration (fabric-dashboard/0.1, DEC-0036 ED-9), under the well-known
 // document's `extensions`. The kit is assets/dashboard-kit; its version is the one in kit.json.
 export const DASHBOARD_EXTENSION_KEY = 'https://fabric.passioncode.ai/agent-contract/extensions/dashboard/0.1';
-export const DASHBOARD_KIT = 'fabric-dashboard-kit@1.0.0';
+export const DASHBOARD_KIT = 'fabric-dashboard-kit@1.1.0';
 export const REFERENCE_THEMES = ['graphite', 'fabric', 'paper', 'forest', 'ocean', 'ember', 'contrast'];
 export const EXIT_ALREADY_RUNNING = 75;
 // Lifecycle contract (fabric-workspace knowledge/lifecycle.md), the same values as fabric_service.py.
@@ -382,7 +382,34 @@ export function dashboardExtension({ minWidth = 360, appearance = ['scheme', 'th
 
 // `extensions` is kept as given (a reader ignores keys it does not know); a dashboard declaration in
 // it must be valid (dashboardExtension builds one).
-export function buildWellKnown({ id, instance, name, version, build, startedAt, status, degraded = [], surfaces, summary, updateAvailable = null, pid = process.pid, extensions }) {
+const PROFILE_ID = /^[a-z][a-z0-9-]{0,62}$/;
+const RUNNER_KIND = /^[a-z][a-z0-9-]{1,62}$/;
+const MODEL_ID = /^[a-z0-9][a-z0-9._-]{0,63}\/[a-z0-9][a-z0-9._:-]{0,127}$/;
+export const ROUTES = Object.freeze(['subscription', 'key']);
+
+/** DEC-0046: the well-known `configuration` — {slots, resolved} as service-well-known.schema.json types it. */
+export function configurationProblems(doc) {
+  if (doc === null || typeof doc !== 'object' || Array.isArray(doc)) return ['configuration is an object'];
+  const problems = Object.keys(doc).filter((k) => k !== 'slots' && k !== 'resolved').map((k) => `configuration has no member ${k}`);
+  const { slots, resolved } = doc;
+  if (!Array.isArray(slots) || slots.length > 2 || new Set(slots).size !== slots.length || !slots.every((s) => s === 'runner' || s === 'model')) problems.push('slots is a list of runner and model, each once');
+  if (resolved === null || typeof resolved !== 'object' || Array.isArray(resolved)) return [...problems, 'resolved is an object'];
+  const checks = {
+    from: (x) => ['request', 'agent', 'binding', 'estate'].includes(x),
+    runnerProfile: (x) => typeof x === 'string' && PROFILE_ID.test(x),
+    modelProfile: (x) => typeof x === 'string' && PROFILE_ID.test(x),
+    runnerKind: (x) => typeof x === 'string' && RUNNER_KIND.test(x),
+    route: (x) => ROUTES.includes(x),
+    models: (x) => Array.isArray(x) && x.length <= 16 && x.every((m) => typeof m === 'string' && MODEL_ID.test(m)),
+  };
+  for (const [k, v] of Object.entries(resolved)) {
+    if (!Object.hasOwn(checks, k)) problems.push(`resolved has no member ${k}`);
+    else if (!checks[k](v)) problems.push(`resolved.${k} is not valid`);
+  }
+  return problems;
+}
+
+export function buildWellKnown({ id, instance, name, version, build, startedAt, status, degraded = [], surfaces, summary, updateAvailable = null, pid = process.pid, extensions, configuration }) {
   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.');
@@ -403,6 +430,11 @@ export function buildWellKnown({ id, instance, name, version, build, startedAt,
     }
     doc.extensions = { ...extensions };
   }
+  if (configuration !== undefined) {
+    const problems = configurationProblems(configuration);
+    if (problems.length) throw new ServiceError(`configuration: ${problems.join('; ')}.`);
+    doc.configuration = configuration;
+  }
   return doc;
 }
 
@@ -450,7 +482,7 @@ const COUNTS = ['inputTokens', 'outputTokens', 'cacheReadTokens', 'cacheWriteTok
  * One model call, from the provider's own usage numbers. No prompt, output or caller.
  * `costUsd` null means it cannot be priced: the report counts it as unpriced, never as $0.
  */
-export function makeUsageReceipt(provider, model, { inputTokens, outputTokens, cacheReadTokens = 0, cacheWriteTokens = 0, costUsd = null, costBasis, at } = {}) {
+export function makeUsageReceipt(provider, model, { inputTokens, outputTokens, cacheReadTokens = 0, cacheWriteTokens = 0, costUsd = null, costBasis, at, route } = {}) {
   if (!PROVIDER.test(provider ?? '')) throw new ServiceError('provider must be a lowercase name such as anthropic or openrouter.');
   model = String(model ?? '').trim();
   if (!model || model.length > 128) throw new ServiceError('model must be 1 to 128 characters.');
@@ -459,7 +491,8 @@ export function makeUsageReceipt(provider, model, { inputTokens, outputTokens, c
   if (costUsd !== null && (typeof costUsd !== 'number' || !Number.isFinite(costUsd) || costUsd < 0)) throw new ServiceError('costUsd must be a non-negative number or null.');
   const basis = costBasis ?? (costUsd === null ? 'unknown' : 'provider');
   if (!COST_BASES.includes(basis) || (costUsd === null) !== (basis === 'unknown')) throw new ServiceError('costBasis is provider or price-list with a cost, unknown without one.');
-  return { at: at ?? nowIso(), provider, model, ...counts, costUsd, costBasis: basis };
+  if (route !== undefined && !ROUTES.includes(route)) throw new ServiceError('route is subscription or key (DEC-0046).');
+  return { at: at ?? nowIso(), provider, model, ...counts, costUsd, costBasis: basis, ...(route === undefined ? {} : { route }) };
 }
 
 const utcDate = (ms) => new Date(ms).toISOString().slice(0, 10);
@@ -482,8 +515,9 @@ export function usageReport(receipts, { id, instance = 'default', now = Date.now
     if (date < first || date > last) continue;
     const rows = days.get(date) ?? new Map();
     days.set(date, rows);
-    const k = `${r.provider}\u0000${r.model}`;
-    const row = rows.get(k) ?? emptyRow({ provider: r.provider, model: r.model, bases: new Set() });
+    const k = `${r.provider}\u0000${r.model}\u0000${r.route ?? ''}`;
+    // DEC-0046: rows of one model on two routes stay apart.
+    const row = rows.get(k) ?? emptyRow({ provider: r.provider, model: r.model, ...(r.route ? { route: r.route } : {}), bases: new Set() });
     rows.set(k, row);
     row.calls += 1;
     for (const c of COUNTS) row[c] += Number(r[c] ?? 0);
@@ -493,7 +527,7 @@ export function usageReport(receipts, { id, instance = 'default', now = Date.now
   const outDays = [...days.keys()].sort().map((date) => {
     const models = [...days.get(date).values()]
       .map(({ bases, ...row }) => closeRow({ ...row, costBasis: bases.size === 1 ? [...bases][0] : 'mixed' }))
-      .sort((a, b) => (a.provider + a.model < b.provider + b.model ? -1 : 1));
+      .sort((a, b) => (`${a.provider}\u0000${a.model}\u0000${a.route ?? ''}` < `${b.provider}\u0000${b.model}\u0000${b.route ?? ''}` ? -1 : 1));
     const day = emptyRow({ date });
     for (const m of models) {
       for (const c of ['calls', 'unpricedCalls', ...COUNTS]) day[c] += m[c];