Merge current dev and refresh PR #6738 from the 7011 integration

scripts/build_frontend.py

@@ -0,0 +1,148 @@
+#!/usr/bin/env python3
+"""Publish explicitly owned native ES modules; never run at application startup."""
+
+import argparse
+import json
+import os
+from pathlib import Path, PurePosixPath
+import shutil
+import subprocess
+import tempfile
+
+
+ROOT = Path(__file__).resolve().parents[1]
+
+
+def module_path(base: Path, relative: str) -> Path:
+    """Accept canonical JS paths only, contained within the declared tree."""
+    if not isinstance(relative, str):
+        raise ValueError("module paths must be strings")
+    parts = PurePosixPath(relative)
+    if (
+        parts.is_absolute()
+        or parts.as_posix() != relative
+        or ".." in parts.parts
+        or "\\" in relative
+        or "?" in relative
+        or "#" in relative
+        or parts.suffix != ".js"
+    ):
+        raise ValueError(f"invalid module path: {relative!r}")
+    path = base / relative
+    if not path.resolve().is_relative_to(base.resolve()):
+        raise ValueError(f"module path escapes its tree: {relative!r}")
+    if any(p.is_symlink() for p in (path, *path.parents)):
+        raise ValueError(f"symlink in module path: {relative!r}")
+    return path
+
+
+def check_lf_attributes(root: Path, paths: set[Path]) -> None:
+    """Require portable, repository-owned LF attributes for every mapped path.
+
+    Ask Git in an isolated temporary repository so global attributes, local
+    info/attributes and alternate Git directories cannot mask missing rules.
+    Copy only attribute files at ancestors of the manifest's source/output paths.
+    """
+    git = shutil.which("git")
+    if git is None:
+        raise ValueError("Git is required for frontend publication attribute checks")
+    attributes = {root / ".gitattributes"}
+    for path in paths:
+        for parent in path.parents:
+            if parent == root:
+                break
+            attributes.add(parent / ".gitattributes")
+    env = {key: value for key, value in os.environ.items() if not key.startswith("GIT_")}
+    env.update(GIT_CONFIG_NOSYSTEM="1", GIT_CONFIG_GLOBAL=os.devnull)
+    relative = sorted(path.relative_to(root).as_posix() for path in paths)
+    with tempfile.TemporaryDirectory(prefix="ody-frontend-attributes-") as directory:
+        target = Path(directory)
+        for attribute in attributes:
+            if attribute.is_symlink():
+                raise ValueError(f"symlink attribute file: {attribute.relative_to(root)}")
+            if attribute.is_file():
+                copy = target / attribute.relative_to(root)
+                copy.parent.mkdir(parents=True, exist_ok=True)
+                copy.write_bytes(attribute.read_bytes())
+        command = [git, "-c", f"core.attributesFile={os.devnull}", "-C", str(target)]
+        try:
+            subprocess.run(command + ["init", "--quiet", "--template="], env=env, check=True, capture_output=True, timeout=15)
+            result = subprocess.run(
+                command + ["check-attr", "-z", "--stdin", "text", "eol"],
+                input=("\0".join(relative) + "\0").encode("utf-8"),
+                env=env, check=True, capture_output=True, timeout=15,
+            )
+        except (subprocess.CalledProcessError, subprocess.TimeoutExpired) as error:
+            raise ValueError("Git frontend attribute check failed") from error
+    fields = result.stdout.decode("utf-8").split("\0")[:-1]
+    effective = {name: {} for name in relative}
+    for index in range(0, len(fields), 3):
+        name, attribute, value = fields[index:index + 3]
+        effective[name][attribute] = value
+    invalid = [
+        f"{name} (text={values.get('text')}, eol={values.get('eol')})"
+        for name, values in effective.items()
+        if values != {"text": "set", "eol": "lf"}
+    ]
+    if invalid:
+        raise ValueError("manifest paths require repository-owned 'text eol=lf' Git attributes: " + ", ".join(invalid))
+
+
+def synchronize(root: Path = ROOT, *, check: bool = False) -> list[str]:
+    """Validate the entire plan before writing. Return stale deployment paths."""
+    root = root.resolve()
+    source_root = root / "frontend" / "src"
+    static_root = root / "static"
+    manifest = json.loads((root / "frontend" / "modules.json").read_text(encoding="utf-8"))
+    if not isinstance(manifest, dict) or manifest.get("version") != 1 or not isinstance(manifest.get("modules"), list):
+        raise ValueError("expected frontend module manifest version 1")
+    if not manifest["modules"]:
+        raise ValueError("module manifest must not be empty")
+    sources, outputs, plan = set(), set(), []
+    for entry in manifest["modules"]:
+        source = module_path(source_root, entry["source"])
+        output = module_path(static_root, entry["deployment"])
+        if not entry["deployment"].startswith("js/"):
+            raise ValueError("deployment modules must be under static/js/")
+        if source in sources or output in outputs:
+            raise ValueError("each source and deployment path must be unique")
+        sources.add(source)
+        outputs.add(output)
+        content = source.read_bytes()
+        if output.exists() and not output.is_file():
+            raise ValueError(f"deployment path is not a file: {output}")
+        plan.append((output, content))
+    unlisted = set(source_root.rglob("*.js")) - sources
+    if unlisted:
+        raise ValueError(f"source modules missing from manifest: {sorted(map(str, unlisted))}")
+    check_lf_attributes(root, sources | outputs)
+    stale = []
+    for output, content in plan:
+        if not output.is_file() or output.read_bytes() != content:
+            stale.append(output.relative_to(root).as_posix())
+    if not check:
+        for output, content in plan:
+            if output.relative_to(root).as_posix() in stale:
+                output.parent.mkdir(parents=True, exist_ok=True)
+                output.write_bytes(content)
+    return stale
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--check", action="store_true", help="fail on invalid attributes or stale output; write no deployment files")
+    args = parser.parse_args()
+    try:
+        stale = synchronize(check=args.check)
+    except (OSError, ValueError, KeyError, TypeError) as error:
+        parser.exit(2, f"frontend: {error}\n")
+    if args.check and stale:
+        print("Stale frontend deployment modules: " + ", ".join(stale))
+        print("Run python scripts/build_frontend.py and include the source and output changes together.")
+        return 1
+    print(f"Frontend {'check passed' if args.check else 'published'} ({len(stale)} changed modules).")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

scripts/check_ca_trust.py

@@ -0,0 +1,180 @@
+#!/usr/bin/env python3
+"""Reject the eMudhra incident's known CA certificates in PEM trust stores.
+
+This checks certificate contents, including OpenSSL's lazily loaded CA directory.
+It does not model native OS certificate revocation or arbitrary custom clients.
+Incident fingerprints: https://emudhra.we-have-a-problem.com/roots.json
+and https://emudhra.we-have-a-problem.com/impacted-intermediates.json
+Cross-signed issuer: https://emudhra.we-have-a-problem.com/chains.zip
+"""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import importlib
+import importlib.util
+import os
+from pathlib import Path
+import re
+import ssl
+import sys
+
+
+BLOCKED_CERTIFICATES = {
+    "86a1ecba089c4a8d3bbe2734c612ba341d813e043cf9e8a862cd5c57a36bbe6b": "emSign ECC Root CA - G3",
+    "d7a7a0fb5d7e2731d771e9484ebcdef71d5f0c3e0a2948782bc83ee0ea699ef4": "AAA Certificate Services",
+    "7dd78d5f4f13459a83dff9abbba62edbaf6f2d102bf257fd712f4d9f2746ed8d": "emSign Root TLS CA - G3",
+    "f2edaaff3d9b701fb4d14c9f285f8c0bad90fc3bcc1fa07d47f4718edaba34a5": "emSign Root CS CA - G3",
+    "3094025792039a68af6e553686410bdab7c0d4a36b9084cba64202e35d6ebbdd": "emSign Root TLS CA - G3 (cross-signed)",
+    # Intermediates can themselves be operator-supplied trust anchors. Include
+    # both published signatures for each key, without parsing SPKI in stdlib.
+    "42c4accd12c4f59597925e1a08a7a90102608543809308d50ec427e118ba1493": "EM DV TLS CA - G3B (eMudhra)",
+    "45a883f349aedfd5f3a649b5498ffb121712ba8b448f3f2a91dbc5a766fcddbe": "EM DV TLS CA - G3B (Sectigo)",
+    "98b896625c0c230adeec3eb2cf6aad5001ecf9156a68644e82374ce5833bc25b": "EM OV TLS CA - G3B (eMudhra)",
+    "5f1ded4dd590af74631290cf073b122a2aac6a1fa479778a0bd43579bd832699": "EM OV TLS CA - G3B (Sectigo)",
+    "e7568fe6e12331f4fd7de61da4c7559d0f8eb192a218d4741a3ba75184333838": "EM EV TLS CA - G3B (eMudhra)",
+    "579480aea166290bd3c643589e795fc0d0e54e86505d180f1dff99efd3199512": "EM EV TLS CA - G3B (Sectigo)",
+    "0164d7ceae5bb909c272af151ff44b1177ae9b47d9424b94f1d9558c30934d19": "EM DV TLS CA - G3C (eMudhra)",
+    "62b7f9868263f72f6911fc78ceaf72c1979158b7368bf648683bb2aa39b02e72": "EM DV TLS CA - G3C (Sectigo)",
+    "cb6e15165ac802e9b3f993f16c25d41f4e81c21ebde71ae1b012ac00bf9c7c3f": "EM OV TLS CA - G3C (eMudhra)",
+    "7485b51c0ed192878fa1d2f948fb529ae1842cc5086c4b67f7be5b2039de9489": "EM OV TLS CA - G3C (Sectigo)",
+    "432ec25f0d28de9006d97bf752f17bbb2cd41f669933fcb072d9a1148d0261f3": "EM EV TLS CA - G3C (eMudhra)",
+    "fd9d5c2dbbd4995ab69b8d50c439d9527b00529199c2fd01b2174eb58f07021f": "EM EV TLS CA - G3C (Sectigo)",
+    "9e39de2881273acc225a149c72ba3e0f51424963669ab633ee1dc7df5db067b4": "EM OV CS CA - G3B (eMudhra)",
+    "a496e23ac0cab8155fc9b117b97eae368efcbb9041aec8804d5a308d2d01c2d8": "EM OV CS CA - G3B (Sectigo)",
+    "4b2460a466f95fd40113bcdcca2ceb29b3b093921de45474da7df48874c630b1": "EM OV CS CA - G3C (eMudhra)",
+    "84112972b8e59d14560ae7e7119654474aad119990cf3722bfc1e3b91615e1fd": "EM OV CS CA - G3C (Sectigo)",
+}
+OVERRIDE_ENV_VARS = (
+    "LLM_CA_BUNDLE", "SSL_CERT_FILE", "REQUESTS_CA_BUNDLE", "CURL_CA_BUNDLE",
+    "PIP_CERT", "NODE_EXTRA_CA_CERTS", "GRPC_DEFAULT_SSL_ROOTS_FILE_PATH",
+)
+
+
+def check_bundle(path: Path) -> None:
+    """Raise on an unreadable, empty, malformed, or affected CA bundle."""
+    context = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
+    context.load_verify_locations(cafile=str(path))
+    # A hashed OpenSSL directory can include valid non-CA certificates (for
+    # example Ubuntu's snakeoil server certificate). get_ca_certs() omits them;
+    # use the total X.509 count to distinguish these from an empty store.
+    if not context.cert_store_stats()["x509"]:
+        raise ValueError("no certificates")
+    certificates = context.get_ca_certs(binary_form=True)
+    blocked = {
+        BLOCKED_CERTIFICATES[fingerprint]
+        for certificate in certificates
+        if (fingerprint := hashlib.sha256(certificate).hexdigest()) in BLOCKED_CERTIFICATES
+    }
+    if blocked:
+        raise ValueError("affected CA certificates: " + ", ".join(sorted(blocked)))
+
+
+def ca_directory_paths(directory: Path) -> list[Path]:
+    """Return the hashed certificate files consumed by OpenSSL's CApath."""
+    return [
+        path for path in directory.iterdir()
+        if re.fullmatch(r"[0-9a-fA-F]{8}\.[0-9]+", path.name) and path.is_file()
+    ]
+
+
+def system_paths() -> list[Path]:
+    """Inspect both the effective OpenSSL CA file and hashed directory entries."""
+    defaults = ssl.get_default_verify_paths()
+    paths = [Path(defaults.cafile)] if defaults.cafile else []
+    # get_default_verify_paths() can report None for a colon-separated
+    # SSL_CERT_DIR even though OpenSSL consumes each directory in that list.
+    capath = os.environ.get(defaults.openssl_capath_env, defaults.capath)
+    if capath:
+        for directory in filter(None, capath.split(os.pathsep)):
+            paths.extend(ca_directory_paths(Path(directory)))
+    if not paths:
+        raise ValueError("no effective OpenSSL PEM CA store found")
+    return paths
+
+
+def override_paths() -> list[Path]:
+    """Inspect every configured override, including client fallback settings."""
+    paths = []
+    for name in OVERRIDE_ENV_VARS:
+        value = os.environ.get(name, "")
+        if name == "LLM_CA_BUNDLE":
+            value = value.strip()  # Match src/tls_overrides.py.
+        if not value:
+            continue
+        path = Path(value)
+        # Requests (also used by pip) accepts either a file or a hashed directory.
+        if name in ("REQUESTS_CA_BUNDLE", "CURL_CA_BUNDLE", "PIP_CERT") and path.is_dir():
+            entries = ca_directory_paths(path)
+            if not entries:
+                raise ValueError(f"{name}: no hashed certificates in {path}")
+            paths.extend(entries)
+        else:
+            paths.append(path)
+    return paths
+
+
+def grpc_roots_path() -> Path:
+    """Select gRPC's override or its independent Python-wheel default bundle."""
+    override = os.environ.get("GRPC_DEFAULT_SSL_ROOTS_FILE_PATH")
+    if override:
+        # gRPC can fall back to its bundled roots when this file is unreadable.
+        # Check the configured file strictly instead of blessing that fallback.
+        return Path(override)
+    spec = importlib.util.find_spec("grpc")
+    if spec is None or spec.origin is None:
+        raise ImportError("grpcio is not installed; cannot check its default roots")
+    return Path(spec.origin).parent / "_cython" / "_credentials" / "roots.pem"
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("bundles", nargs="*", type=Path)
+    parser.add_argument("--system", action="store_true", help="check effective OpenSSL PEM stores")
+    parser.add_argument("--python", action="store_true", help="check certifi and pip's separate vendored bundle")
+    parser.add_argument("--grpc", action="store_true", help="check gRPC's selected default CA file")
+    parser.add_argument("--overrides", action="store_true", help="check configured LLM/HTTPX/Requests/pip/Node/gRPC CA overrides")
+    parser.add_argument("--verbose", action="store_true", help="show the runtime identity, Python executable and selected CA paths")
+    args = parser.parse_args(argv)
+    if not (args.bundles or args.system or args.python or args.grpc or args.overrides):
+        parser.error("select --system, --python, --grpc, --overrides, or explicit PEM bundle paths")
+    if args.verbose:
+        print(f"Python executable: {sys.executable}")
+        print(f"Python prefix: {sys.prefix}")
+        print(f"User home: {Path.home()}")
+        if hasattr(os, "geteuid"):
+            print(f"Effective user: uid={os.geteuid()} gid={os.getegid()}")
+    try:
+        paths = list(args.bundles)
+        if args.system:
+            paths.extend(system_paths())
+        if args.python:
+            for name in ("certifi", "pip._vendor.certifi"):
+                paths.append(Path(importlib.import_module(name).where()))
+        if args.grpc:
+            paths.append(grpc_roots_path())
+        if args.overrides:
+            paths.extend(override_paths())
+        paths = list(dict.fromkeys(path.resolve() for path in paths))
+        if not paths:
+            raise ValueError("no CA bundle files selected; also select --system, --python, or an explicit path")
+        errors = []
+        for path in paths:
+            if args.verbose:
+                print(f"CA bundle: {path}")
+            try:
+                check_bundle(path)
+            except (OSError, ValueError, ssl.SSLError) as exc:
+                errors.append(f"{path}: {exc}")
+        if errors:
+            raise ValueError("\n".join(errors))
+    except (ImportError, OSError, ValueError, ssl.SSLError) as exc:
+        print(str(exc), file=sys.stderr)
+        return 1
+    print(f"Validated {len(paths)} CA bundle file(s): no known eMudhra incident CA certificates")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

scripts/check_frontend.mjs

@@ -0,0 +1,180 @@
+/** Architecture gates for maintained source. Legacy static modules stay under existing guards. */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parse } from 'acorn';
+
+const layers = ['domain', 'application', 'infrastructure', 'ui'];
+const platformIdentifiers = new Set(['window', 'document', 'globalThis', 'navigator', 'localStorage', 'sessionStorage', 'fetch', 'Notification', 'indexedDB', 'WebSocket', 'XMLHttpRequest', 'Worker', 'setTimeout', 'setInterval', 'clearTimeout', 'clearInterval', 'requestAnimationFrame', 'cancelAnimationFrame', 'performance', 'eval', 'Function']);
+
+function ownership(source) {
+  const parts = source.split('/');
+  if (parts[0] === 'app' && parts.length >= 2) return { feature: 'app', layer: 'index' };
+  if (parts[0] === 'shared') {
+    if (parts.length === 2) return { feature: 'shared', layer: 'domain' };
+    const layer = { domain: 'domain', platform: 'infrastructure', ui: 'ui' }[parts[1]];
+    if (layer) return { feature: 'shared', layer };
+  }
+  if (parts[0] === 'features' && parts.length >= 3) {
+    if (['app', 'shared'].includes(parts[1])) throw new Error(`reserved feature name: ${parts[1]}`);
+    if (parts.length === 3 && parts[2] === 'index.js') return { feature: parts[1], layer: 'index' };
+    if (layers.includes(parts[2]) && parts.length >= 4) return { feature: parts[1], layer: parts[2] };
+  }
+  throw new Error(`unsupported source ownership: ${source}`);
+}
+
+export function allowsDependency(from, to) {
+  const a = ownership(from), b = ownership(to);
+  if (b.feature === 'app') return a.feature === 'app';
+  if (a.feature === 'app') return b.feature === 'shared' || b.layer === 'index';
+  if (b.feature === 'shared') {
+    const shared = { domain: ['domain'], application: ['domain'], infrastructure: ['domain', 'infrastructure'], ui: ['domain', 'infrastructure', 'ui'], index: layers };
+    return shared[a.layer].includes(b.layer);
+  }
+  if (a.feature === 'shared') return false;
+  if (a.feature !== b.feature) return ['application', 'index'].includes(a.layer) && b.layer === 'index';
+  const internal = { domain: ['domain'], application: ['domain', 'application'], infrastructure: ['domain', 'infrastructure'], ui: ['domain', 'application', 'ui'], index: layers };
+  return internal[a.layer].includes(b.layer);
+}
+
+export function imports(source, { domain = false } = {}) {
+  const ast = parse(source, { ecmaVersion: 'latest', sourceType: 'module', locations: true });
+  const found = [];
+  function visit(node, parent, field) {
+    if (!node || typeof node !== 'object') return;
+    // Domain modules use explicit values/ports, including an injected clock.
+    // Keep platform vocabulary out even when a local binding shadows a global.
+    const propertyName = parent && !parent.computed && (
+      (parent.type === 'MemberExpression' && field === 'property') ||
+      (['Property', 'MethodDefinition'].includes(parent.type) && field === 'key' && !parent.shorthand)
+    );
+    if (domain && !propertyName && node.type === 'Identifier' && platformIdentifiers.has(node.name)) {
+      throw new Error(`platform identifier in domain at line ${node.loc.start.line}: ${node.name}`);
+    }
+    if (domain && ((node.type === 'MemberExpression' && node.object.name === 'Date' && (node.property.name === 'now' || node.property.value === 'now')) || (['CallExpression', 'NewExpression'].includes(node.type) && node.callee.name === 'Date' && !node.arguments.length))) {
+      throw new Error(`ambient clock in domain at line ${node.loc.start.line}; inject time`);
+    }
+    if (['ImportDeclaration', 'ExportNamedDeclaration', 'ExportAllDeclaration', 'ImportExpression'].includes(node.type) && node.source) {
+      if (node.source.type !== 'Literal' || typeof node.source.value !== 'string') {
+        throw new Error(`computed import at line ${node.loc.start.line}; use explicit import thunks`);
+      }
+      found.push({ specifier: node.source.value, line: node.loc.start.line, dynamic: node.type === 'ImportExpression' });
+    }
+    for (const [key, value] of Object.entries(node)) {
+      if (Array.isArray(value)) value.forEach(item => visit(item, node, key));
+      else if (value && typeof value === 'object' && value.type) visit(value, node, key);
+    }
+  }
+  visit(ast);
+  return found;
+}
+
+export function checkArchitecture(root) {
+  const manifest = JSON.parse(fs.readFileSync(path.join(root, 'frontend/modules.json'), 'utf8'));
+  const bySource = new Map(manifest.modules.map(m => [m.source, m]));
+  const byOutput = new Map(manifest.modules.map(m => [`/static/${m.deployment}`, m.source]));
+  const graph = new Map();
+  const errors = [];
+  const sw = fs.readFileSync(path.join(root, 'static/sw.js'), 'utf8');
+  // Parse the actual manifest arrays, not comments or unrelated strings.
+  const swAst = parse(sw, { ecmaVersion: 'latest', sourceType: 'script' });
+  const precached = new Set();
+  for (const statement of swAst.body) {
+    for (const declaration of statement.declarations || []) {
+      if (['PRECACHE', 'PANEL_PRECACHE'].includes(declaration.id.name)) {
+        for (const item of declaration.init.elements) {
+          if (item?.type === 'Literal' && typeof item.value === 'string') precached.add(item.value);
+        }
+      }
+    }
+  }
+  for (const module of manifest.modules) {
+    try {
+      const owner = ownership(module.source);
+      const deployed = `/static/${module.deployment}`;
+      if (!precached.has(deployed)) throw new Error(`deployment URL absent from explicit precache: ${deployed}`);
+      const dependencies = [];
+      const exceptions = module.legacyImports || [];
+      const used = new Set();
+      for (const { specifier, line } of imports(fs.readFileSync(path.join(root, 'frontend/src', module.source), 'utf8'), { domain: owner.layer === 'domain' })) {
+        const fail = message => { throw new Error(`line ${line}: ${message}: ${specifier}`); };
+        const runtime = new URL(specifier, `https://odysseus.invalid${deployed}`);
+        if (!runtime.pathname.startsWith('/static/js/') || !runtime.pathname.endsWith('.js') || runtime.pathname.includes('%')) fail('runtime imports must name canonical static JS paths');
+        let target;
+        if (specifier.startsWith('.')) {
+          if (runtime.search || runtime.hash) fail('maintained modules use one unversioned URL identity');
+          target = path.posix.normalize(path.posix.join(path.posix.dirname(module.source), specifier));
+          if (!bySource.has(target)) fail('relative import must name maintained source');
+          if (runtime.pathname !== `/static/${bySource.get(target).deployment}`) fail('source and deployment relative paths resolve differently');
+        } else if (specifier.startsWith('/static/')) {
+          target = byOutput.get(runtime.pathname);
+          if (!target) {
+            const exception = exceptions.find(e => e.specifier === specifier && e.reason?.trim());
+            if (!exception || !['index', 'infrastructure', 'ui'].includes(owner.layer) || owner.feature === 'shared') fail('legacy import requires an explicit module-scoped rationale at a composition, infrastructure or UI boundary');
+            if (!fs.statSync(path.join(root, runtime.pathname.slice(1))).isFile()) fail('legacy target does not exist');
+            used.add(exception);
+            continue;
+          }
+        } else fail('bare, external and source-tree runtime imports are unsupported');
+        if (runtime.search || runtime.hash) fail('maintained modules use one unversioned URL identity');
+        if (!allowsDependency(module.source, target)) fail(`forbidden dependency on ${target}`);
+        dependencies.push(target);
+      }
+      if (exceptions.some(e => !used.has(e))) throw new Error('unused legacy import exception');
+      graph.set(module.source, dependencies);
+    } catch (error) { errors.push(`${module.source}: ${error.message}`); }
+  }
+  const visiting = new Set(), visited = new Set();
+  function visit(source, trail = []) {
+    if (visiting.has(source)) throw new Error(`maintained-source dependency cycle: ${[...trail, source].join(' -> ')}`);
+    if (visited.has(source)) return;
+    visiting.add(source);
+    for (const target of graph.get(source) || []) visit(target, [...trail, source]);
+    visiting.delete(source);
+    visited.add(source);
+  }
+  try { for (const source of graph.keys()) visit(source); }
+  catch (error) { errors.push(error.message); }
+  if (errors.length) throw new Error(errors.join('\n'));
+  return graph.size;
+}
+
+export function inventory(root) {
+  const staticRoot = path.join(root, 'static');
+  const files = fs.readdirSync(staticRoot, { recursive: true }).map(p => p.split(path.sep).join('/')).filter(p => p.endsWith('.js') && !p.startsWith('lib/') && !p.startsWith('js/editor/build/')).sort();
+  const graph = new Map(), fan = new Map(), missing = [];
+  let staticImports = 0, dynamicLiteralImports = 0;
+  for (const file of files) {
+    const targets = [];
+    for (const { specifier, dynamic } of imports(fs.readFileSync(path.join(staticRoot, file), 'utf8'))) {
+      if (!specifier.startsWith('.') && !specifier.startsWith('/static/')) continue;
+      const target = new URL(specifier, `https://odysseus.invalid/static/${file}`).pathname.slice('/static/'.length);
+      if (dynamic) dynamicLiteralImports++;
+      else { staticImports++; targets.push(target); }
+      fan.set(target, (fan.get(target) || 0) + 1);
+      if (!fs.existsSync(path.join(staticRoot, target))) missing.push({ file, specifier });
+    }
+    graph.set(file, targets);
+  }
+  const indices = new Map(), low = new Map(), stack = [], active = new Set(), staticCycles = [];
+  function visit(v) {
+    indices.set(v, indices.size); low.set(v, indices.get(v)); stack.push(v); active.add(v);
+    for (const w of graph.get(v) || []) {
+      if (!indices.has(w)) { visit(w); low.set(v, Math.min(low.get(v), low.get(w))); }
+      else if (active.has(w)) low.set(v, Math.min(low.get(v), indices.get(w)));
+    }
+    if (low.get(v) === indices.get(v)) {
+      const component = []; let w;
+      do { w = stack.pop(); active.delete(w); component.push(w); } while (w !== v);
+      if (component.length > 1) staticCycles.push(component.sort());
+    }
+  }
+  for (const file of files) if (!indices.has(file)) visit(file);
+  return { files: files.length, staticImports, dynamicLiteralImports, missing, fanIn: [...fan].sort((a, b) => b[1] - a[1]).slice(0, 8), staticCycles };
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+  try { console.log(process.argv.includes('--inventory') ? JSON.stringify(inventory(root), null, 2) : `Frontend architecture passed (${checkArchitecture(root)} maintained modules).`); }
+  catch (error) { console.error(error.message); process.exitCode = 1; }
+}

scripts/generate_env_reference.py

@@ -914,6 +914,80 @@ VARIABLE_NOTES: dict[str, tuple[str, str, str]] = {
         "Overrides the source commit reported for runtime provenance, for builds "
         "that ship without a git directory.",
     ),
+
+    # -- Photo editor and image operations -----------------------------------
+    "ODYSSEUS_EDITOR_AGENT_BASES": (
+        "Model routing and providers", USER,
+        "Comma-separated base URLs for the image-editor agent backends; a single "
+        "base URL in the model endpoint config wins over this list.",
+    ),
+    "ODYSSEUS_ALLOW_LOCAL_IMAGE_MODELS": (
+        "Model routing and providers", USER,
+        "Set to 1, true, yes or on to allow local image-generation and editing "
+        "backends to be reachable as image providers.",
+    ),
+    "ODYSSEUS_IMAGE_OPS_BASE": (
+        "Model routing and providers", USER,
+        "Base URL of the image-operations backend (inpaint, outpainting and style "
+        "transfer); a trailing slash is stripped before use.",
+    ),
+    "ODYSSEUS_IMAGE_EDIT_MAX_SIDE": (
+        "Upload and media limits", USER,
+        "Maximum pixel side (width or height) an edited image is downscaled to "
+        "before it is sent to the image backend.",
+    ),
+    "ODYSSEUS_IMAGE_EDIT_MAX_STEPS": (
+        "Upload and media limits", USER,
+        "Maximum number of iterative edit steps the image backend may perform in "
+        "a single request.",
+    ),
+    "ODYSSEUS_IMAGE_OUTPAINT_TIMEOUT": (
+        "Upload and media limits", USER,
+        "Seconds the outpainting proxy waits for the image backend before giving "
+        "up on a single request.",
+    ),
+    "ODYSSEUS_JEFF_": ("Agent loop and tool execution", INTERNAL, "Prefix for per-job decision adapter opt-ins; each job is disabled by default."),
+    "ODYSSEUS_JEFF_TIMEOUT": ("Agent loop and tool execution", INTERNAL, "Timeout in seconds for a decision adapter request."),
+    "ODYSSEUS_JEFF_URL": ("Agent loop and tool execution", INTERNAL, "Base URL of the optional decision adapter service."),
+    "ODYSSEUS_PRIVATE_BROWSER_LEGACY": ("Agent loop and tool execution", INTERNAL, "Explicit opt-in to the legacy browser compatibility transport; disabled by default."),
+    "ODYSSEUS_SPEC_BROWSER_FALLBACK": ("Agent loop and tool execution", INTERNAL, "Optional browser routing fallback: mcp, web, or 0 to disable."),
+    "ODYSSEUS_SPEC_DRIVER_TOPK": ("Agent loop and tool execution", INTERNAL, "Number of router-selected tool candidates exposed in a driver round."),
+    "ODYSSEUS_SPEC_MODE": ("Agent loop and tool execution", INTERNAL, "Spec routing mode for explicitly configured models, including strict and driver."),
+    "ODYSSEUS_SPEC_ROUTER_MIN_CONF": ("Agent loop and tool execution", INTERNAL, "Minimum tool-selection confidence accepted from the router."),
+    "ODYSSEUS_SPEC_ROUTER_MODEL": ("Agent loop and tool execution", INTERNAL, "Decision adapter model used for tool routing."),
+    "ODYSSEUS_SPEC_ROUTER_SECOND": ("Agent loop and tool execution", INTERNAL, "Minimum confidence for adding a secondary tool candidate."),
+    "ODYSSEUS_SPEC_ROUTER_TIMEOUT": ("Agent loop and tool execution", INTERNAL, "Time budget in seconds for a router decision."),
+    "ODYSSEUS_SPEC_ROUTER_URL": ("Agent loop and tool execution", INTERNAL, "Base URL of the optional Spec router; an empty URL disables requests."),
+    "ODYSSEUS_SPEC_SUBSET_OF_BASE": ("Agent loop and tool execution", INTERNAL, "Limit Spec tool selections to the existing request inventory by default."),
+    "ODYSSEUS_SPEC_THINK_MIN_P": ("Agent loop and tool execution", INTERNAL, "Minimum router confidence for enabling thinking."),
+    "ODYSSEUS_SPEC_THINK_MODEL": ("Agent loop and tool execution", INTERNAL, "Optional thinking decision adapter model, falling back to the tool router model."),
+    "ODYSSEUS_SPEC_THINK_QUESTION": ("Agent loop and tool execution", INTERNAL, "Thinking classifier question format: binary or kind5."),
+    "ODYSSEUS_SPEC_THINK_ROUTER": ("Agent loop and tool execution", INTERNAL, "Enable router thinking decisions for explicitly configured Spec models."),
+    "ODYSSEUS_SPEC_TOOL_FORMAT": ("Agent loop and tool execution", INTERNAL, "Use names for compact router tool signatures, otherwise include descriptions."),
+    "ODYSSEUS_SPEC_TRIM_PROMPT": ("Agent loop and tool execution", INTERNAL, "Enable prompt trimming for the selected Spec tool menu."),
+    "ODYSSEUS_VISION_MAX_SIDE": ("Upload and media limits", USER, "Maximum pixel side for image attachments sent directly to a vision model."),
+    "ODYSSEUS_VISION_MODELS": ("Model routing and providers", USER, "Comma-separated model-name fragments that explicitly support inline images."),
+    "ODYSSEUS_VISION_PROBE": ("Model routing and providers", USER, "Allow a cached vision-capability probe against local model endpoints."),
+    "ODYSSEUS_SPEC_DIRECT_MODE": (
+        "Agent loop and tool execution", INTERNAL,
+        "Controls how the spec router answers high-confidence direct-answer turns; "
+        "either tool_choice_none (default) or empty_menu.",
+    ),
+    "ODYSSEUS_SPEC_DIRECT_NOTOOLS": (
+        "Agent loop and tool execution", INTERNAL,
+        "Set to 1, true, yes or on to enable the spec router's direct-answer "
+        "no-tools path for high-confidence answer_directly decisions.",
+    ),
+    "ODYSSEUS_SPEC_DIRECT_MIN_P": (
+        "Agent loop and tool execution", INTERNAL,
+        "Minimum confidence probability a spec-router direct-answer decision must "
+        "reach before the no-tools path is taken.",
+    ),
+    "ODYSSEUS_GRACEFUL_SHUTDOWN_TIMEOUT": (
+        "Deployment and first run", INTERNAL,
+        "Seconds the server waits for in-flight requests and background loops to "
+        "finish during a graceful shutdown.",
+    ),
 }
 
 

scripts/verify_frontend_runtime.py

@@ -0,0 +1,81 @@
+#!/usr/bin/env python3
+"""Verify the current Python runtime from an isolated distribution without frontend tooling."""
+import os
+import json
+from pathlib import Path
+import shutil
+import socket
+import subprocess
+import sys
+import tempfile
+
+ROOT = Path(__file__).resolve().parents[1]
+
+PROBE = """
+from pathlib import Path
+import shutil
+import json
+import sys
+from starlette.testclient import TestClient
+from app import app
+assert not Path('frontend').exists()
+assert not Path('node_modules').exists()
+assert shutil.which('node') is None
+with TestClient(app) as client:
+    for output in json.loads(sys.argv[1]):
+        asset = client.get('/static/' + output)
+        assert asset.status_code == 200, (output, asset.status_code)
+        assert asset.content == Path('static', output).read_bytes(), output
+        assert asset.headers['content-type'].startswith('text/javascript'), output
+        assert asset.headers['cache-control'] == 'no-cache', output
+    response = client.get('/static/js/actionMenuOrder.js')
+    assert response.status_code == 200, response.status_code
+    assert response.content == Path('static/js/actionMenuOrder.js').read_bytes()
+    assert response.headers['content-type'].startswith('text/javascript'), response.headers
+    assert response.headers['cache-control'] == 'no-cache', response.headers
+    assert "script-src 'self' 'nonce-" in response.headers['content-security-policy'], response.headers
+    assert client.get('/frontend/src/shared/actionMenuOrder.js').status_code == 404
+    assert client.get('/static/%2e%2e/app.py').status_code == 404
+    shell = client.get('/')
+    assert shell.status_code == 200, shell.status_code
+    assert '{{CSP_NONCE}}' not in shell.text
+    assert '/static/app.js' in shell.text
+print('PASS: isolated Python lifespan, shell, deployed bytes, MIME, revalidation, CSP and source-tree 404')
+"""
+
+
+def main() -> int:
+    with tempfile.TemporaryDirectory(prefix="ody-f1-distribution-") as directory, socket.socket() as chroma_guard:
+        target = Path(directory)
+        for name in ("app.py", "HARNESS_VERSION"):
+            shutil.copy2(ROOT / name, target / name)
+        for name in ("core", "routes", "src", "services", "resources", "mcp_servers", "companion", "config", "static", "scripts"):
+            shutil.copytree(ROOT / name, target / name, ignore=shutil.ignore_patterns("__pycache__", "node_modules", ".env", "secrets.env*", "*.db", "*.sqlite*"))
+        # Reserve a non-listening port so initialization cannot reach a real store.
+        chroma_guard.bind(("127.0.0.1", 0))
+        env = dict(os.environ)
+        env.update(
+            ODYSSEUS_DATA_DIR=str(target / "data"),
+            DATABASE_URL="sqlite:///:memory:",
+            AUTH_ENABLED="false",
+            ODYSSEUS_STARTUP_WARMUPS="0",
+            ODYSSEUS_TOOL_INDEX_PREWARM="0",
+            CHROMADB_HOST="127.0.0.1",
+            CHROMADB_PORT=str(chroma_guard.getsockname()[1]),
+            FASTEMBED_CACHE_PATH=str(target / "fastembed"),
+            PATH=str(target / "no-development-tools"),
+        )
+        # A caller's Python search path must not import the original checkout.
+        env.pop("PYTHONPATH", None)
+        outputs = [entry['deployment'] for entry in json.loads(
+            (ROOT / 'frontend/modules.json').read_text(encoding='utf-8')
+        )['modules']]
+        result = subprocess.run([sys.executable, "-c", PROBE, json.dumps(outputs)], cwd=target, env=env, capture_output=True, text=True, timeout=60)
+        print(result.stdout, end="")
+        if result.returncode:
+            print(result.stderr[-8000:], file=sys.stderr)
+        return result.returncode
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

scripts/verify_notes_browser_runtime.py

@@ -0,0 +1,76 @@
+#!/usr/bin/env python3
+"""Run real Notes UI and API against a disposable native distribution and database."""
+import os
+from pathlib import Path
+import shutil
+import socket
+import subprocess
+import sys
+import tempfile
+import time
+from urllib.request import urlopen
+
+ROOT = Path(__file__).resolve().parents[1]
+
+
+def main():
+    with tempfile.TemporaryDirectory(prefix="ody-notes-native-") as directory, socket.socket() as chroma_guard:
+        target = Path(directory)
+        for name in ("app.py", "HARNESS_VERSION"):
+            shutil.copy2(ROOT / name, target / name)
+        for name in ("core", "routes", "src", "services", "resources", "mcp_servers", "companion", "config", "static"):
+            shutil.copytree(ROOT / name, target / name, ignore=shutil.ignore_patterns("__pycache__", ".env", "secrets.env*", "*.db", "*.sqlite*"))
+        chroma_guard.bind(("127.0.0.1", 0))
+        with socket.socket() as app_port:
+            app_port.bind(("127.0.0.1", 0))
+            port = app_port.getsockname()[1]
+        env = dict(os.environ)
+        env.update(
+            ODYSSEUS_DATA_DIR=str(target / "data"),
+            DATABASE_URL="sqlite:///" + str(target / "notes.db"), AUTH_ENABLED="true",
+            ODYSSEUS_STARTUP_WARMUPS="0", ODYSSEUS_TOOL_INDEX_PREWARM="0",
+            CHROMADB_HOST="127.0.0.1", CHROMADB_PORT=str(chroma_guard.getsockname()[1]),
+            FASTEMBED_CACHE_PATH=str(target / "fastembed"),
+        )
+        env.pop("PYTHONPATH", None)
+        server = subprocess.Popen(
+            [sys.executable, "-m", "uvicorn", "app:app", "--host", "127.0.0.1", "--port", str(port)],
+            cwd=target, env=env, stdout=subprocess.PIPE, stderr=subprocess.STDOUT, text=True,
+        )
+        result = None
+        try:
+            origin = f"http://127.0.0.1:{port}"
+            deadline = time.monotonic() + 45
+            while time.monotonic() < deadline:
+                if server.poll() is not None:
+                    raise RuntimeError("Disposable Notes server exited during startup")
+                try:
+                    with urlopen(origin + "/", timeout=1) as response:
+                        if response.status == 200:
+                            break
+                except OSError:
+                    time.sleep(0.1)
+            else:
+                raise RuntimeError("Disposable Notes server did not become ready")
+            result = subprocess.run(
+                ["node", "tests/browser/notesNative.mjs"], cwd=ROOT,
+                env=dict(os.environ, ODYSSEUS_NOTES_RUNTIME_ORIGIN=origin, NOTES_TEST_PYTHON=sys.executable),
+                capture_output=True, text=True, timeout=120,
+            )
+            print(result.stdout, end="")
+            if result.returncode:
+                print(result.stderr, file=sys.stderr)
+            return result.returncode
+        finally:
+            server.terminate()
+            try:
+                logs, _ = server.communicate(timeout=10)
+            except subprocess.TimeoutExpired:
+                server.kill()
+                logs, _ = server.communicate()
+            if result is None or result.returncode:
+                print(logs[-8000:], file=sys.stderr)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())