GodModeAI2025/SkillSafe / wissenstresor
wissenstresor
FlaggedLokaler, evidenzgebundener Wissensspeicher als portabler purer Skill (Profil oksv-lite über Google OKF v0.1/v0.2). Beantwortet Fragen AUSSCHLIESSLICH aus kuratierten Claims: deterministisches Hybrid-Retrieval aus Begriffswelten, Wortformen und einem Graph-Hop meldet, wie gut es die Frage verstanden hat; die Bedeutungssuche ist eine Vollsichtung aller Claims mit Quittung — ohne Cloud, Vektorstore oder Embeddings. Bindet Bilder, Scans und PDFs über geprüfte Regionen an Claims. Belegt fremdes Material satzweise über Anker auf aufgeführte externe Quellen, mit Live-Nachschlagen im Fallback. Meldet ungedecktes Wissen als "Nicht im Bestand", nie aus Modellwissen ergänzt. IMMER verwenden bei: Wissenstresor, SkillSafe, Knowledge Vault, "frag den Tresor", "steht das im Bestand", Bedeutungssuche, semantische Suche, Vollsichtung, Begriffswelt, Synonym, Hybrid Retrieval, RAG-ähnliche Suche, Bild oder PDF in den Tresor, Quelle einlesen, Bestand prüfen, externe Quelle, Satzanker, fremdes Repo, OKF, Quellenregister.
scripts/vault.py
View on GitHub#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""vault.py — deterministische Engine des Wissenstresors (Profil: oksv-lite/1.3).
Arbeitsteilung: Dieses Script erledigt ALLES, was deterministisch geht
(Prüfen, Indizieren, Graph ableiten, Suchen, Hashen, Loggen, Zählen).
Das Sprachmodell kuratiert und urteilt nur — es rechnet nie Prüfsummen,
verifiziert nie Links "im Kopf" und baut nie Indizes von Hand.
Determinismus-Garantie: gleiche Eingaben ⇒ byte-identische Ausgaben.
Erzeugte Artefakte (INDEX.md, graph.json, MANIFEST.sha256) enthalten
darum bewusst KEINE Zeitstempel. Nur Standardbibliothek, keine Abhängigkeiten.
Kommandos:
validate Schema-, Referenz- und Integritätsprüfung (fail-closed)
index INDEX.md aus den Frontmatter-Daten neu erzeugen
graph graph/graph.json (Wissensgraph) ableiten
search <begriff> Deterministische Volltextsuche (Hilfe bei Synonymen)
query <frage> Lokales Hybrid-Retrieval als stabiler JSON-Vertrag
(--extern: zusätzlich aufgeführte externe Quellen lesen)
sweep <frage> Vollsichtung: jeden Claim in Stapeln vorlegen und die
Quittung prüfen (--batch n | --receipt …)
media-template ID JSON-Gerüst für eine registrierte Bild-/PDF-Quelle
extern Aufgeführte externe Bezugsquellen: list/bind/unbind
anchor-template Sätze eines externen Dokuments mit Index und Digest
orchestrator-template Katalog-Gerüst für einen externen Markdown-Baum
checksum MANIFEST.sha256 schreiben | checksum --verify: prüfen
log <aktion> <txt> Log-Eintrag mit grep-barem Präfix anhängen
stats Bestandszahlen (Domänen, Typen, Claims, Kanten)
source <datei> Hash + nächste freie S-ID + fertige Registerzeile
route <frage> Frage deterministisch auf Domäne und Seiten routen
doctor Gesamtdiagnose mit Ampel-Report (validate + Drift + Orphans)
release [stufe] Transaktionaler Release mit Lock und Rollback
export --okf Bestand als OKF-v0.2-Bundle außerhalb des Tresors ausgeben
"""
import argparse
import contextlib
import hashlib
import heapq
import io
import json
import os
import re
import shutil
import stat
import sys
import tempfile
import unicodedata
from datetime import date
from pathlib import Path
# Die Ausgabe ist UTF-8, auch wenn die Umgebung etwas anderes vorgibt. Auf
# einer cp1252-Konsole (Windows-Voreinstellung) starb sonst jedes Kommando mit
# UnicodeEncodeError an der Ampel, statt lesbar zu bleiben. Nicht darstellbare
# Zeichen werden ersetzt, nie verschluckt.
for _strom in (sys.stdout, sys.stderr):
if hasattr(_strom, "reconfigure"):
try:
_strom.reconfigure(encoding="utf-8", errors="backslashreplace")
except (AttributeError, OSError, ValueError):
pass
ROOT = Path(__file__).resolve().parent.parent
KNOWLEDGE = ROOT / "knowledge"
SOURCES = ROOT / "sources"
QUARANTINE = SOURCES / "quarantine"
RAW = SOURCES / "raw"
REGISTER = SOURCES / "REGISTER.md"
TYPES = ROOT / "schema" / "types.yaml"
CONCEPTS = ROOT / "schema" / "begriffswelten.json"
ROUTER = ROOT / "ROUTER.md"
INDEX = ROOT / "INDEX.md"
GRAPH = ROOT / "graph" / "graph.json"
DERIVED = SOURCES / "derived"
MANIFEST = ROOT / "MANIFEST.sha256"
LOG = ROOT / "log.md"
VERSION = ROOT / "VERSION"
RELEASE_LOCK = ROOT / ".vault-release.lock"
EXTERN_REGISTER = SOURCES / "EXTERN.md"
# Maschinenlokale Bindung externer Wurzeln. Bewusst AUSSERHALB des Manifests
# (siehe _tracked_path), genau wie log.md: ein absoluter Pfad ist eine
# Eigenschaft dieses Hosts, nicht des Artefakts. Ohne Bindung antwortet der
# Tresor vollständig — externe Auflösung meldet dann fail-closed "not_bound".
BINDUNG = ROOT / ".vault-extern.json"
PROFIL = "oksv-lite/1.3"
REQUIRED_FIELDS = ["type", "title", "domain", "status", "confidence",
"version", "stand", "sources", "tags"]
OPTIONAL_FIELDS = {"relations", "concepts", "geprueft_von", "geprueft_am",
"externe_quellen"}
# Optionale Skalarfelder brauchen eine eigene Typprüfung: die Textschleife in
# lade_seiten deckt nur Pflichtfelder ab, die Listenschleife nur LIST_FIELDS.
# Ohne diesen Satz würde 'geprueft_von:' ohne Wert stillschweigend zur leeren
# Liste und eine Inline-Liste als Wert bis in die Regex-Prüfung durchrutschen.
OPTIONAL_SCALAR_FIELDS = {"geprueft_von", "geprueft_am"}
LIST_FIELDS = {"sources", "tags", "relations", "concepts", "externe_quellen"}
STATUS_WERTE = {"aktiv", "veraltet", "in-pruefung"}
CONF_WERTE = {"hoch", "mittel", "niedrig"}
LOG_AKTIONEN = {"ingest", "update", "lint", "release", "note", "onboarding",
"extern"}
TRUST_WERTE = {"T1", "T2", "T3"}
TYPE_REQUIRED_FIELDS = {
"beschreibung", "kriterien", "besonderheiten", "pflicht_extra", "graph_rolle"
}
# Split-Kandidaten (doctor, nur Hinweis): keine harte Obergrenze, kein
# automatisches Zerschneiden — Schwellen markieren nur, wann ein Mensch/
# das Modell die Kompressions- bzw. Beförderungsregel prüfen sollte.
SPLIT_CLAIMS_SCHWELLE = 20
SPLIT_ZEILEN_SCHWELLE = 400
CLAIM_START = "- **C-"
# Eine Zeilenform, Präfix-Dispatch: S- ist eine lokal gehashte Quelle, X- eine
# aufgeführte externe Bezugsquelle. Eine zweite Regex wäre schlechter — die
# eine lehrbare Zeilenform ist das, was die Grammatik trägt.
CLAIM_RE = re.compile(
r"^- \*\*(C-\d{4})\*\* \[((?:S|X)-\d{4}) \| ([^\]|]+?) \| "
r"(Wortlaut|Beobachtung|Auslegung)\] (.+)$")
REL_RE = re.compile(r"^([a-z_]+) -> (.+)$")
LINK_RE = re.compile(r"\]\(([^)]*)\)")
REFERENCE_LINK_RE = re.compile(
r"(?m)^[ \t]{0,3}\[[^\]\r\n]+\]:[ \t]*(\S.*)$"
)
HTML_LINK_RE = re.compile(r"<(?:a|img)\b", re.IGNORECASE)
DATE_RE = re.compile(r"^\d{4}-\d{2}-\d{2}$")
# Aktorgrammatik für geprueft_von. Bewusst strenger als OKF v0.2 §7: die Spec
# fixiert nur das Präfix, nicht den Zeichenvorrat. Deutsche Präfixe, weil der
# ganze Vertrag deutsch ist; die Abbildung auf human:/process: gehört in einen
# späteren Export, nicht in den Bestand.
ACTOR_RE = re.compile(
r"^(?:mensch:[a-z0-9][a-z0-9._-]{0,63}"
r"|prozess:[a-z0-9][a-z0-9._-]{0,63}"
r"|agent:[A-Za-z0-9][A-Za-z0-9._-]{0,63}/[A-Za-z0-9][A-Za-z0-9._-]{0,63})$"
)
# Trust-Tiers nach OKF v0.2 §5.3. Sie werden ausschließlich ABGELEITET, nie
# gespeichert, und gehen niemals in das Ranking ein: sonst würde aus einem
# reproduzierbaren Score ein Vertrauensurteil (AD-01).
TIER_UNVERIFIED = "unverified"
TIER_MACHINE = "machine-confirmed"
TIER_HUMAN = "human-reviewed"
# ---- OKF-Export (nur ausgehend; der Tresor konsumiert kein fremdes OKF) ----
OKF_VERSION = "0.2"
# Die einzige Stelle exakter semantischer Deckung zwischen beiden Welten.
STATUS_OKF = {"aktiv": "stable", "veraltet": "deprecated", "in-pruefung": "draft"}
# Aktorpräfixe nach OKF v0.2 §7. Die Rückrichtung ist bei Großbuchstaben in
# IDs nicht eindeutig; der Export ist bewusst eine Einbahnstraße.
ACTOR_OKF = {"mensch:": "human:", "prozess:": "process:", "agent:": ""}
# Ein exportiertes Bundle hat keine Engine, kein Manifest und keine Regeln.
# Landet es in einem Skill-Ladeort, lädt ein Agent es als Wissensquelle ohne
# jede Absicherung. Genau diese Vermischung verhindert AD-06.
EXPORT_VERBOTENE_SEGMENTE = {".claude", ".codex"}
VERSION_RE = re.compile(r"^\d+\.\d+\.\d+$")
SID_RE = re.compile(r"^S-\d{4}$")
CID_RE = re.compile(r"^C-\d{4}$")
WORLD_ID_RE = re.compile(r"^BW-\d{4}$")
CONCEPT_ID_RE = re.compile(r"^B-\d{4}$")
REGION_ID_RE = re.compile(r"^R-\d{4}$")
XID_RE = re.compile(r"^X-\d{4}$")
ANCHOR_ID_RE = re.compile(r"^A-\d{4}$")
BINDUNGSSCHLUESSEL_RE = re.compile(r"^[a-z0-9][a-z0-9-]{0,63}$")
HASH_RE = re.compile(r"^[0-9a-f]{64}$")
CONCEPT_SCHEMA = "skillsafe.begriffswelten/v1"
MEDIA_SCHEMA = "skillsafe.media/v1"
QUERY_SCHEMA = "skillsafe.query/v1"
ANCHORS_SCHEMA = "skillsafe.anchors/v1"
ORCHESTRATOR_SCHEMA = "skillsafe.orchestrator/v1"
BINDING_SCHEMA = "skillsafe.bindung/v1"
# Lokal gilt hybrid-local/v4 (Wortform, Funktionswörter, Trefferstärke; siehe
# schema/profil.md). extern-zweistufig/v2: Stoppwörter werden wie die Anfrage
# normalisiert — in v1 wirkte „für" nie als Stoppwort, weil das rohe Wort mit
# dem Token „fuer" verglichen wurde. Dazu liest v2 lokale Quellen vollständig,
# filtert über den Katalog nur noch bei Netzquellen und zählt Abrufe je Abfrage.
# extern-zweistufig/v3: Die Funktionswörter der Frage (FUNKTIONSWOERTER, wie
# lokal; ein Kürzel in Großbuchstaben bleibt) sind kein Anfragebegriff mehr.
# In v2 trafen „sie", „nur" oder „ohne" beliebige Sätze, und jeder Treffer
# verlangt in der Antwort eine eigene Zeile.
RETRIEVAL_PROFILE = "hybrid-local/v4"
EXTERN_RETRIEVAL_PROFILE = "extern-zweistufig/v3"
SEGMENTATION_PROFILE = "satzsegmentierung/v1"
# Wortform ist kein Bedeutungsmodell: nur Flexion, Umlaut-Plural, -ung und
# Kompositumteile, alles nachrechenbar. Bedeutung liest das Modell in der
# Vollsichtung ('sweep'); diese Stufe sorgt nur dafür, dass eine Frage nicht
# an einer Endung scheitert.
WORTFORM_PROFILE = "wortform/v1"
SWEEP_SCHEMA = "skillsafe.sweep/v1"
SWEEP_STANDARD_GROESSE = 40
SWEEP_MIN_GROESSE = 5
SWEEP_MAX_GROESSE = 200
SWEEP_SIEGEL_LAENGE = 16
# Was zwischen zwei Aufrufen derselben Frage schwankt, ohne dass sich die
# Frage ändert: die Art der Anführungszeichen und Striche. Sie werden
# vereinheitlicht, nicht entfernt: 5' und 5" bleiben verschieden.
SWEEP_ZEICHEN_GLEICH = str.maketrans({
**{zeichen: '"' for zeichen in "„“”«»″"},
**{zeichen: "'" for zeichen in "‚‘’‹›′`´"},
**{zeichen: "-" for zeichen in "‐‑‒–—−"},
})
SWEEP_QUITTUNG_RE = re.compile(
r"^(\d{1,6}):([0-9a-f]{16})=(-|C-\d{4}(?:,C-\d{4})*)$"
)
KOMPOSITUM_MIN_TEIL = 4
MAX_OMITTED_PAGES = 20
# Wörter, die eine Frage nach einer Kennung nur einleiten oder verbinden
# ("Was steht in C-9999?", "Worum geht es in S-0099?"). Sie zählen allein für
# die Frage, ob eine Frage nichts als unbekannte Kennungen nennt
# (fallback.unknown_ids_only). Die Liste ist geschlossen: Jedes andere Wort
# ist ein Sachwort, auch ein Homograph wie "Waren" oder "Soll", den das
# Ranking als Funktionswort überliest, und auch "Aussage" oder "Inhalt".
# Verben, die zugleich ein Substantiv sind ("regeln", "sagen", "lauten",
# "stehen"), stehen deshalb nicht darin. Für das Ranking sind diese Wörter
# gewöhnliche Wörter.
KENNUNG_RAHMENWOERTER = frozenset("""
was wer wie wo wozu worum woraus wofuer woran worueber welche welcher welches
welchen welchem der die das den dem des ein eine einen einem einer eines diese
dieser dieses diesen diesem in im ins zu zum zur ueber laut nach von vom bei
beim mit auf fuer um an am es sich ist sind gibt geht handelt gilt und oder
sowie denn eigentlich genau bitte mir uns drin darin steht sagt besagt besagen
enthaelt enthalten bedeutet bedeuten heisst heissen meint meinen gemeint regelt
beschreibt beschreiben nennt nennen erklaert erklaere erklaeren erklaer zeigt
zeige zeigen lautet existiert existieren
""".split())
# Bindewörter verbinden nur Kennungen ("C-9998 und C-9999"); sonst hängen sie
# eine zweite Frage an ("Welche Regeln gibt es und was steht in C-9999?").
KENNUNG_BINDEWOERTER = frozenset({"und", "oder", "sowie"})
# Hinter einem Artikel, einer Form von "dieser" oder "welche" und hinter
# einer Präposition mit Artikel steht ein Substantiv, auch kleingeschrieben:
# "was ist ein laut in c-9999", "zum aus", "das stehen". Dort darf nur eine
# Kennung stehen ("in der Quelle S-0099", "was steht im C-9999").
KENNUNG_DETERMINATIVE = frozenset("""
der die das den dem des ein eine einen einem einer eines diese dieser dieses
diesen diesem welche welcher welches welchen welchem zum zur beim vom im am ins
""".split())
# Satzzeichen und Auszeichnung gliedern eine Frage nur. Jedes andere Zeichen
# außerhalb der Wörter ist ein Sachwort ("Was bedeutet § in C-9999?").
KENNUNG_GLIEDERUNG_RE = re.compile(
r"[\s.,;:!?'\"„“”‚‘’«»‹›()\[\]{}\-‐‑‒–—…/*_`]+")
# Ein Substantiv, das die Kennung nur benennt, zählt allein unmittelbar vor
# ihr ("die Quelle S-0099", "die Kennungen C-9998 und C-9999"). Anderswo ist
# es die gefragte Sache: "Was ist ein Claim laut S-0099?".
KENNUNG_NOMEN_RE = re.compile(
r"(?i)(?<![^\W\d_])(?:kennung(?:en)?|ids?|claims?|quellen?"
r"|begriff(?:e|en)?|eintr(?:ag|äge|aege|ägen|aegen)|nummern?)[ \t]+"
r"(?=[CSB]-[0-9]{4}(?![A-Za-z0-9]))")
# Als Kennung zählt nur die Schreibung mit ASCII-Ziffern, wie in der Frage
# selbst (build_query_result): "C-0001" ist ein gewöhnliches Wort.
KENNUNG_ALLE_RE = re.compile(r"(?i)(?<![A-Z0-9])[CSB]-[0-9]{4}(?![A-Z0-9])")
KENNUNG_PLATZHALTER = "zzkennungzz"
# fallback.page_paths nannte bis v2 jede Seite des Bestands, als Arbeitsliste
# des alten Rückfalls ("alle Seiten lesen"). Den Rückfall trägt seither die
# Vollsichtung; die Liste blähte bei 1.500 Seiten jede Abfrage um rund 65 kB
# auf. Sie bleibt als Feld bestehen, ist aber gedeckelt.
MAX_FALLBACK_SEITEN = 50
MAX_JSON_BYTES = 2 * 1024 * 1024
MAX_QUERY_LENGTH = 1000
MAX_QUERY_LIMIT = 20
MAX_CONCEPT_EXPANSIONS = 32
# ---- Externe Bezugsquellen -------------------------------------------------
# Eine aufgeführte Bezugsquelle ist KEINE Internetrecherche: Titel, Art, Ziel,
# Trust und Rechte stehen namentlich in sources/EXTERN.md und sind über
# MANIFEST.sha256 gepinnt. Es gibt keinen Codepfad, der ein Ziel aus einer
# Anfrage, einem Dokument oder einer Antwort übernimmt.
EXTERN_ARTEN = {"markdown-tree", "skillsafe-vault"}
EXTERN_SCOPES = {"organisation", "fachbereich", "projekt", "persoenlich"}
EXTERN_BLOCK_ARTEN = {"absatz", "listenpunkt", "tabellenzelle", "ueberschrift",
"zitat"}
# Budgets werden GEZÄHLT, nie über eine Uhr gestoppt: ein Wall-Clock-Limit
# würde die Determinismus-Garantie aus dem Modul-Docstring brechen. Nur der
# Netzpfad kennt ein Zeitlimit, und der ist ausdrücklich als nicht
# reproduzierbar gekennzeichnet.
MAX_EXTERN_TIEFE = 12
MAX_EXTERN_EINTRAEGE = 20000
MAX_EXTERN_DOKUMENTE = 5000
MAX_EXTERN_BYTES_JE_DATEI = 1 * 1024 * 1024
MAX_EXTERN_BYTES_GESAMT = 64 * 1024 * 1024
# Stufe 1 filtert nur bei Netzquellen: dort ist jedes Öffnen ein Abruf. Eine
# lokale Quelle wird vollständig gelesen; der Katalog ordnet sie nur.
MAX_EXTERN_STUFE1 = 24
MAX_EXTERN_TREFFER = 8
MAX_EXTERN_TOP_TOKENS = 12
# Ein Dokument ohne einen einzigen Anfragebegriff als ganzes Token fliegt raus,
# egal wie gut der Katalogtext aussah. Gezählt werden getroffene Begriffe, nicht
# die gerundete Abdeckung: bei mehr als 100 Begriffen rundete die einen echten
# Treffer auf 0 % ab.
EXTERN_MIN_BEGRIFFE = 1
# Netzgrenzen. Nur https, nur unter dem registrierten Präfix, nie eine
# Suchmaschine, nie ein Link aus dem Inhalt.
EXTERN_NETZ_TIMEOUT = 10
EXTERN_NETZ_MAX_REDIRECTS = 3
# Netzabrufe je Abfrage, gezählt über alle Netzquellen. Ein Cache-Treffer ist
# kein Abruf; ein gescheiterter Versuch ist einer.
EXTERN_NETZ_MAX_ABRUFE = 20
EXTERN_CACHE_TTL = 6 * 3600
EXTERN_OFFLINE_ENV = "SKILLSAFE_OFFLINE"
# Ein Satz, eine Schreibweise. Jeder externe Zustand, bei dem kein Dokument
# gelesen wurde, trägt ihn im Grund: „nicht gelesen" darf nie wie „gelesen und
# nichts gefunden" aussehen. Antwort-Workflow und Tests halten sich daran fest.
EXTERN_KEIN_BEFUND = "dies ist kein Negativbefund"
MEDIA_TYPES = {
".png": "image/png",
".jpg": "image/jpeg",
".jpeg": "image/jpeg",
".gif": "image/gif",
".webp": "image/webp",
".tif": "image/tiff",
".tiff": "image/tiff",
".pdf": "application/pdf",
}
ACTIVE_MEDIA_SUFFIXES = {".svg"}
# Erlaubte Dateiarten im Tresorbaum: Wissen ist Text, Registry oder
# registriertes Medium, die Engine ist genau EIN Python-Script. Alles andere
# (Archive, Binaries, Shellskripte, ein zweites Script) bricht fail-closed ab,
# und kein Tresorinhalt darf ausführbar sein. Aktive Bildformate bleiben über
# ACTIVE_MEDIA_SUFFIXES draußen.
ARTEFAKT_SUFFIXE = {".md", ".json", ".yaml", ".sha256"} | set(MEDIA_TYPES)
ARTEFAKT_DATEINAMEN = {"LICENSE", "VERSION"}
ENGINE_SCRIPT = "scripts/vault.py"
# OKF v0.2 §3.1 belegt diese Namen; sie duerfen keine Wissensseite sein.
RESERVIERTE_DATEINAMEN = {"index.md", "log.md"}
REGION_KINDS = {"text", "diagram", "table", "photo", "chart", "other"}
EXTRACTOR_KINDS = {"human", "model", "ocr", "hybrid"}
# Die lange Formel steht einmal: Der Stolperdraht über Absätze hinweg und die
# Pfadregel prüfen nur sie (IGNORE_SIGNATUR_RE), jedes Textfeld alle Formeln.
IGNORE_FORMEL = (
r"ignore\s+(?:(?:all|any)\s+)?(?:(?:previous|prior)\s+)?instructions")
PROMPT_INJECTION_RE = re.compile(
r"(?:" + IGNORE_FORMEL + r"|"
r"system\s+prompt|developer\s+message|<\s*system\s*>)",
re.IGNORECASE,
)
def _hat_signatur(wert):
"""Trägt ein Textfeld eine offensichtliche Instruktionssignatur?"""
return isinstance(wert, str) and bool(PROMPT_INJECTION_RE.search(wert))
def _ohne_signatur(eintrag, felder):
"""Kuratierte Textfelder so, wie query und sweep sie ausgeben.
Claim und Fundstelle mit Instruktionssignatur sind nie freigabefähig.
Titel, Tags und Registerangaben sind kuratierter Text daneben: validate
meldet eine Signatur dort als Warnung, und die Ausgabe lässt das Feld weg
(None; aus einer Liste nur den betroffenen Eintrag). Der Eintrag trägt
dann ``suspicious_instruction: true``. Ohne Treffer bleibt er, wie er ist,
auch ohne das Feld."""
markiert = False
for feld in felder:
wert = eintrag.get(feld)
if isinstance(wert, list):
sauber = [teil for teil in wert if not _hat_signatur(teil)]
if len(sauber) != len(wert):
eintrag[feld] = sauber
markiert = True
elif _hat_signatur(wert):
eintrag[feld] = None
markiert = True
if markiert:
eintrag["suspicious_instruction"] = True
return eintrag
# Was im Rumpf einen eigenen Block beginnt: Überschrift, Listenpunkt,
# Tabellenzeile (_blockstart). Code-Zäune und HTML-Kommentare führt
# _freitext_laeufe eigens. Leerraum ist hier nur Leerzeichen und Tabulator:
# Ein geschütztes Leerzeichen ist Inhalt (CommonMark).
FREITEXT_UEBERSCHRIFT_RE = re.compile(r"^[ \t]{0,3}#{1,6}(?:[ \t]|$)")
FREITEXT_LISTENPUNKT_RE = re.compile(
r"^[ \t]{0,3}(?:[-*+]|\d{1,3}[.)])(?:[ \t]+|$)")
FREITEXT_TABELLE_RE = re.compile(r"^[ \t]{0,3}\|")
# "# Text" nach beliebigem Leerraum: sieht aus wie eine Überschrift.
FREITEXT_RAUTE_ALS_TITEL_RE = re.compile(r"^\s*#{1,6}(?:\s|$)")
# Ein Code-Zaun, auch eingerückt in einem Listenpunkt: Zeichen, Länge und
# der Info-String dahinter. Ein Backtick-Zaun hat keinen Backtick im
# Info-String, sonst ist die Zeile Inline-Code.
FREITEXT_ZAUN_RE = re.compile(r"^[ \t]*(`{3,}|~{3,})(.*)$")
FREITEXT_ZITAT_RE = re.compile(r"^[ \t]{0,3}(?:>[ \t]?)+")
# Vor "#" und "<!--" zählt jeder Leerraum, wie im Frontmatter-Parser (eine
# Zeile mit geschütztem Leerzeichen vor "#" überspringt er als Kommentar);
# danach nur Leerzeichen und Tabulator, denn was folgt, ist Inhalt.
FREITEXT_HTML_KOMMENTAR_RE = re.compile(r"^\s*<!--[ \t]?|[ \t]?-->\s*$")
# Nur die lange Formel verbindet der Stolperdraht auch über Absätze hinweg:
# "ignore … instructions" entsteht über eine Überschrift kaum zufällig, die
# Zweiwortformeln ("System" vor einem Absatz, der mit "Prompt" beginnt) schon.
IGNORE_SIGNATUR_RE = re.compile(IGNORE_FORMEL, re.IGNORECASE)
def _leer(text):
"""Leerzeile nach CommonMark: nur Leerzeichen und Tabulator. Ein
geschütztes Leerzeichen ist Inhalt und trennt keinen Absatz."""
return not text.strip(" \t\r")
def _ohne_kommentarzeichen(zeile):
"""Eine Kommentarzeile ohne ihr "#" (Frontmatter, Code-Zaun). Davor fällt
jeder Leerraum weg, wie im Frontmatter-Parser; ob die Zeile leer ist,
entscheidet _leer am Rest, und dort ist ein geschütztes Leerzeichen
Inhalt."""
return zeile.lstrip().lstrip("#")
def _ist_kommentarzeile(zeile):
"""Was der Frontmatter-Parser als Kommentar überspringt: "#" nach
beliebigem Leerraum. Er und der Stolperdraht teilen diese Regel, damit
keine übersprungene Zeile ungeprüft bleibt."""
return zeile.lstrip().startswith("#")
def _einzug(zeile):
return len(zeile.expandtabs(4)) - len(zeile.expandtabs(4).lstrip(" "))
def _blockstart(zeile):
"""Beginnt die Zeile einen eigenen Block: Überschrift, Listenpunkt oder
Tabellenzeile?"""
return bool(FREITEXT_UEBERSCHRIFT_RE.match(zeile)
or FREITEXT_LISTENPUNKT_RE.match(zeile)
or FREITEXT_TABELLE_RE.match(zeile))
def _freitext_laeufe(datei_zeilen, offset, rumpf_zeilen):
"""Der Freitext einer Seite in Läufen, wie ein Leser ihn zusammenliest.
Zitatzeichen fallen zuerst weg; was danach bleibt, entscheidet. Eine
Leerzeile beendet den Lauf, ein neuer Block (Überschrift, Listenpunkt,
Tabellenzeile) beginnt einen neuen, und eine Überschrift steht für sich,
auch in einem HTML-Kommentar. Kommentare bilden eigene Läufe und werden
nie mit Text oder Code verbunden: "#"-Zeilen im Frontmatter, in einem
Code-Zaun und in einem eingerückten Codeblock außerhalb eines
Listenpunkts (ohne das "#"; eine leere Kommentarzeile trennt) und
HTML-Kommentare, auch über mehrere Zeilen; Text hinter einem Kommentar,
der in derselben Zeile schließt, gehört zum Absatz. Als Kommentarzeile
gilt, was der Frontmatter-Parser überspringt (_ist_kommentarzeile); eine
Codezeile bleibt ganz, auch mit "#" darin. Ein Listenpunkt bleibt offen,
bis nach einer Leerzeile eine Zeile ohne Einzug folgt, auch ein Zaun
oder ein HTML-Kommentar. Ein Code-Zaun gilt nach CommonMark: Er öffnet
mit höchstens drei Leerzeichen Einzug, in einem Listenpunkt auch tiefer
und direkt auf der Listenmarke; er schließt nur mit demselben Zeichen in
mindestens derselben Länge, ohne Text dahinter, außerhalb eines
Listenpunkts mit höchstens drei Leerzeichen Einzug, in einem Listenpunkt
höchstens drei tiefer als die Öffnung. Sein Info-String ist ein eigener
Lauf, und die Codezeilen darin bilden Läufe wie Absätze. Eine
Claim-Zeile beginnt einen Lauf wie ein Listenpunkt; ihre Fortsetzung
gehört dazu. Zurück kommen Läufe aus (Zeilennummer, Text, ist_claim).
Abschnittsweise liest _freitext_abschnitte."""
laeufe, lauf = [], []
art = None
def schliessen():
nonlocal art
if lauf:
laeufe.append(list(lauf))
lauf.clear()
art = None
def anhaengen(nummer, text, neue_art):
# Eine andere Art beginnt einen neuen Lauf; nur die Fortsetzung
# einer Claim-Zeile bleibt bei ihr.
nonlocal art
if art != neue_art and not (art == "claim" and neue_art == "text"):
schliessen()
art = neue_art
lauf.append((nummer, text, neue_art == "claim"))
def kommentar_anhaengen(nummer, zeile):
# Eine "#"-Zeile ohne ihr "#"; eine leere trennt.
text = _ohne_kommentarzeichen(zeile)
if _leer(text):
schliessen()
else:
anhaengen(nummer, text.strip(" \t"), "kommentar")
def code_anhaengen(nummer, zeile):
# Einen Code-Kommentar liest das Modell mit. Eine Codezeile bleibt
# ganz, auch mit "#" darin: Ob es ein Kommentar ist oder ein String,
# sagt erst die Sprache.
if _ist_kommentarzeile(zeile):
kommentar_anhaengen(nummer, zeile)
elif _leer(zeile):
schliessen()
else:
anhaengen(nummer, zeile, "code")
for nummer, zeile in enumerate(datei_zeilen[:offset], 1):
if 1 < nummer < offset and _ist_kommentarzeile(zeile):
kommentar_anhaengen(nummer, zeile)
else:
schliessen()
schliessen()
zaun = None
im_html = in_liste = code_block = False
nach_leer = True
for bn, zeile in enumerate(rumpf_zeilen, 1):
nummer = offset + bn
if zeile.startswith(CLAIM_START) and zaun is None and not im_html:
schliessen()
anhaengen(nummer, zeile, "claim")
in_liste, nach_leer, code_block = True, False, False
continue
rest = FREITEXT_ZITAT_RE.sub("", zeile)
if zaun is not None:
zeichen, laenge, grenze = zaun
schluss = FREITEXT_ZAUN_RE.match(rest)
if (schluss and schluss.group(1)[0] == zeichen
and len(schluss.group(1)) >= laenge
and _leer(schluss.group(2))
and _einzug(rest) <= grenze):
schliessen()
zaun = None
nach_leer = False
else:
code_anhaengen(nummer, rest)
continue
breit = rest.expandtabs(4)
einzug = len(breit) - len(breit.lstrip(" "))
# Ein Zaun öffnet am Zeilenanfang, auch direkt hinter einer
# Listenmarke ("- ```bash"); außerhalb eines Listenpunkts mit
# höchstens drei Leerzeichen Einzug.
punkt = FREITEXT_LISTENPUNKT_RE.match(breit)
kandidat = breit[punkt.end():] if punkt else breit
oeffnung = FREITEXT_ZAUN_RE.match(kandidat)
if (oeffnung and not (oeffnung.group(1)[0] == "`"
and "`" in oeffnung.group(2))
and (punkt or einzug <= 3 or in_liste)):
schliessen()
if nach_leer and not punkt and not rest[:1].isspace():
# Nach einer Leerzeile beendet ein Zaun ohne Einzug die
# Liste wie eine Textzeile.
in_liste = False
if punkt:
in_liste = True
grenze = punkt.end() + 3
elif in_liste:
grenze = einzug + 3
else:
grenze = 3
zaun = (oeffnung.group(1)[0], len(oeffnung.group(1)), grenze)
if not _leer(oeffnung.group(2)):
# Der Info-String steht sichtbar da: ein eigener Lauf.
anhaengen(nummer, oeffnung.group(2).strip(" \t"), "info")
schliessen()
nach_leer = code_block = False
continue
if im_html or rest.lstrip().startswith("<!--"):
if not im_html and nach_leer and not rest[:1].isspace():
# Ebenso ein HTML-Kommentar ohne Einzug.
in_liste = False
oeffnet, schliesst = rest.rfind("<!--"), rest.rfind("-->")
# Ohne "<!--" in der Zeile war der Kommentar schon offen.
im_html = oeffnet > schliesst if oeffnet >= 0 else schliesst < 0
danach = ""
if not im_html and schliesst >= 0:
# Was hinter "-->" steht, ist sichtbarer Text des Absatzes.
danach = rest[schliesst + 3:]
rest = rest[:schliesst + 3]
kommentar = FREITEXT_HTML_KOMMENTAR_RE.sub("", rest)
if _leer(kommentar):
schliessen()
else:
if _blockstart(kommentar):
schliessen()
anhaengen(nummer, kommentar, "html")
if FREITEXT_UEBERSCHRIFT_RE.match(kommentar):
schliessen()
if not _leer(danach):
anhaengen(nummer, danach, "text")
nach_leer = code_block = False
continue
if _leer(rest):
schliessen()
nach_leer = True
continue
# Ein eingerückter Codeblock: nach einer Leerzeile vier Spalten tief
# (ein Tabulator zählt vier), außerhalb eines Listenpunkts. Seine
# Kommentarzeilen werden verbunden wie im Zaun, nie mit dem Code.
code_block = (einzug >= 4 and not in_liste
and (nach_leer or code_block))
nach_leer_vorher, nach_leer = nach_leer, False
if code_block:
code_anhaengen(nummer, rest)
continue
ueberschrift = bool(FREITEXT_UEBERSCHRIFT_RE.match(breit))
if ueberschrift or punkt or FREITEXT_TABELLE_RE.match(breit):
schliessen()
in_liste = bool(punkt)
elif nach_leer_vorher and not rest[:1].isspace():
# Nach einer Leerzeile beendet eine Zeile ohne Einzug die Liste;
# direkt hinter dem Text eines Punkts setzt sie ihn fort.
in_liste = False
if not ueberschrift and FREITEXT_RAUTE_ALS_TITEL_RE.match(rest):
# "# Text" hinter einem geschützten Leerzeichen oder tiefer
# eingerückt ist keine Überschrift, sieht aber so aus; geprüft
# wird der Text dahinter, mit dem Absatz. Ein Hashtag ("#ki")
# bleibt, wie er ist.
rest = _ohne_kommentarzeichen(rest)
anhaengen(nummer, rest, "text")
if ueberschrift:
schliessen()
schliessen()
return laeufe
def _freitext_abschnitte(datei_zeilen, offset, rumpf_zeilen):
"""Der Freitext einer Seite in Abschnitten, für die lange Formel über
Absätze hinweg (IGNORE_SIGNATUR_RE): Nur Claim-Zeilen und die übrigen
Frontmatter-Zeilen trennen. Eine Claim-Zeile beginnt einen Abschnitt;
Zitat-, HTML-Kommentar- und Kommentarzeichen fallen weg. Zurück kommen
Läufe wie bei _freitext_laeufe."""
laeufe, lauf = [], []
def schliessen():
if lauf:
laeufe.append(list(lauf))
lauf.clear()
for nummer, zeile in enumerate(datei_zeilen[:offset], 1):
if 1 < nummer < offset and _ist_kommentarzeile(zeile):
lauf.append(
(nummer, _ohne_kommentarzeichen(zeile).strip(" \t"), False))
else:
schliessen()
schliessen()
for bn, zeile in enumerate(rumpf_zeilen, 1):
nummer = offset + bn
if zeile.startswith(CLAIM_START):
schliessen()
lauf.append((nummer, zeile, True))
continue
rest = FREITEXT_HTML_KOMMENTAR_RE.sub(
"", FREITEXT_ZITAT_RE.sub("", zeile))
if _ist_kommentarzeile(rest):
rest = _ohne_kommentarzeichen(rest).strip(" \t")
lauf.append((nummer, rest, False))
schliessen()
return laeufe
def _freitext_signaturen(laeufe, muster=PROMPT_INJECTION_RE):
"""Dateizeilen, an denen im Freitext eine Instruktionssignatur liegt.
Jeder Lauf wird als ein Text geprüft: Die Signatur verlangt Leerraum
zwischen den Wörtern, und ein Zeilenumbruch ist Leerraum. Gemeldet wird
die erste Zeile des Fundes außerhalb einer Claim-Zeile; ein Fund ganz in
einer Claim-Zeile ist dort schon ein Fehler. Je Zeile höchstens ein
Treffer."""
treffer = set()
for lauf in laeufe:
text = "\n".join(teil for _, teil, _ in lauf)
for fund in muster.finditer(text):
erste = text.count("\n", 0, fund.start())
letzte = text.count("\n", 0, max(fund.end() - 1, fund.start()))
ausserhalb = [lauf[i][0] for i in range(erste, letzte + 1)
if not lauf[i][2]]
if ausserhalb:
treffer.add(ausserhalb[0])
return sorted(treffer)
PFAD_WORTTRENNER_RE = re.compile(r"[-_.]+|%20")
def _pfad_mit_signatur(pfad):
"""Trägt ein Pfad eine Instruktionssignatur?
Mit Leerzeichen zählt jede Formel. Mit Bindestrich, Unterstrich, Punkt
oder %20 zwischen den Wörtern zählt nur die lange Formel "ignore …
instructions": Die Zweiwortformeln sind als Dateiname üblich
("system-prompt-grundlagen.md", "developer-message-format.md") und
bleiben dort, wie ein Titel in dieser Schreibung, ohne Befund."""
if not isinstance(pfad, str):
return False
return _hat_signatur(pfad) or bool(IGNORE_SIGNATUR_RE.search(
PFAD_WORTTRENNER_RE.sub(" ", pfad)))
# Zugangsdaten im ausgelieferten Wissen. Bewusst wenige, präzise Formen statt
# einer Entropie-Heuristik: ein Fehlalarm blockiert validate und damit jeden
# Release, also zählt jede Form nur, wenn sie praktisch nie zufällig in Prosa
# vorkommt. Ein Tresor wird kopiert, paketiert und exportiert; was einmal im
# Paket steckt, ist nicht mehr zurückzuholen.
SECRET_RE = re.compile(
r"(?:-----BEGIN (?:[A-Z]+ )*PRIVATE KEY-----"
r"|\b(?:AKIA|ASIA)[0-9A-Z]{16}\b"
r"|\bgh[pousr]_[A-Za-z0-9]{36,}"
r"|\bgithub_pat_[A-Za-z0-9_]{40,}"
r"|(?<![\w-])sk-(?:ant-|proj-)?[A-Za-z0-9_-]{32,}"
r"|\bxox[abprs]-[A-Za-z0-9-]{20,}"
r"|\bAIza[0-9A-Za-z_-]{35}\b"
r"|\beyJ[A-Za-z0-9_-]{10,}\.eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}"
r"|\b[a-z][a-z0-9+.-]*://[^/\s:@<>\"'`]+:[^/\s:@<>\"'`]+@)"
)
SECRET_SUFFIXE = {".md", ".json", ".yaml"}
# Dokumentation zeigt Zugangsdaten oft als Muster: ghp_xxxx…, sk-proj-XXXX…,
# den AWS-Doku-Schlüssel …EXAMPLE, das Beispiel-JWT von jwt.io oder
# postgres://user:password@host. Solche Platzhalter sind kein Geheimnis und
# dürfen den Release nicht blockieren.
SECRET_BEISPIEL_SIGNATUREN = {"SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"}
SECRET_URL_PLATZHALTER = {
"pass", "passwd", "password", "passwort", "pw", "pwd", "secret", "geheim",
"token", "changeme",
}
def _secret_platzhalter(fund):
"""Ob ein Musterfund erkennbar ein Doku-Platzhalter statt eines Geheimnisses ist."""
if "://" in fund:
passwort = fund.rsplit("@", 1)[0].split("://", 1)[1].split(":", 1)[1]
return (passwort.lower() in SECRET_URL_PLATZHALTER
or passwort[:1] in {"$", "{", "%", "*"}
or len(set(passwort.lower())) == 1)
if "example" in fund.lower() or fund.rsplit(".", 1)[-1] in SECRET_BEISPIEL_SIGNATUREN:
return True
# Längster Abschnitt des Rumpfs aus höchstens zwei Zeichen (xxxx, XXXX, 0000).
rumpf = max(re.split(r"[_.-]", fund[4:]), key=len)
return len(rumpf) >= 12 and len(set(rumpf.lower())) <= 2
RETRIEVAL_STOPWORDS = {
"aber", "als", "auch", "auf", "aus", "bei", "das", "dem", "den", "der",
"des", "die", "ein", "eine", "einer", "eines", "für", "hat", "ich", "im",
"in", "ist", "mit", "nach", "oder", "sich", "sind", "und", "von", "vor",
"was", "welche", "welcher", "wie", "wo", "zu", "zum", "zur",
"a", "an", "and", "are", "for", "from", "how", "in", "is", "of", "on",
"or", "the", "to", "what", "which", "with",
}
# Funktionswörter des lokalen Rankings (seit hybrid-local/v2), in der normalisierten
# Schreibung von _retrieval_norm (ae/oe/ue/ss). Bewusst eine ZWEITE Liste und
# keine Erweiterung von RETRIEVAL_STOPWORDS: die alte Liste formt auch die
# nachrechenbaren Katalogzahlen (token_count, top_tokens). Sie bleibt
# unberührt, damit sich dort kein Wert verschiebt; seit extern-zweistufig/v2
# wird sie nur noch normalisiert (RETRIEVAL_STOPWORDS_NORM). Seit
# extern-zweistufig/v3 nimmt auch die externe Suche diese Liste aus den
# Anfragebegriffen, aber nur auf der Seite der Frage (_anfragebegriffe).
#
# Aufgenommen sind nur geschlossene Wortklassen (Artikel, Pronomen,
# Präpositionen, Konjunktionen, Hilfs- und Modalverben, Partikeln) plus die
# bedeutungsleeren Stützverben 'gibt' und 'machen'. Gemessen am Demo-Bestand:
# ohne diese Liste traf eine Alltagsfrage nach Mietkürzung bei feuchten
# Wänden über ihr 'darf' einen Claim zu Agenten-Parametern, lieferte
# 'candidates_found' und schaltete damit genau die Vollprüfung ab, die die
# Frage gebraucht hätte.
#
# Homographen sind der Preis: nach casefold ist 'Macht' nicht mehr von 'macht'
# zu unterscheiden, 'Waren' nicht von 'waren', 'Soll' nicht von 'soll'. Sie
# stehen trotzdem hier, weil die Folge harmlos ist und die umgekehrte nicht:
# eine Frage ohne Inhaltswort endet in 'match_strength: none' und damit in
# der Pflicht-Vollsichtung, nie in einem stillen Fehltreffer. Als kuratiertes
# Label einer Begriffswelt bleibt jedes dieser Wörter exakt auffindbar, weil
# Begriffe gegen die ungefilterte Frage abgeglichen werden.
#
# Zwei Grenzen der Liste seit hybrid-local/v3. Englische Einträge, die nach
# casefold ein deutsches Hauptwort sind, stehen nicht mehr hier: 'not' (Not),
# 'all' (All), 'most' (Most), 'same' (Same). Und eine Abkürzung in
# Großbuchstaben ist nie ein Funktionswort (siehe _inhaltstokens): Sonst wäre
# "die IT" das englische 'it' und fiele spurlos aus der Frage.
FUNKTIONSWOERTER = frozenset("""
der die das den dem des ein eine einen einem einer eines kein keine keinen
keinem keiner keines
ich du er sie es wir ihr mich dich sich uns euch mir dir ihm ihn ihnen
mein meine meinen meinem meiner meines dein deine deinen deinem deiner deines
sein seine seinen seinem seiner seines ihre ihren ihrem ihrer ihres
unser unsere unseren unserem unserer euer eure euren
man jemand niemand etwas nichts alles alle allen aller allem
dies diese diesen diesem dieser dieses jene jenen jenem jener jenes
welche welcher welches welchen welchem solche solchen solchem solcher solches
selbst selber
was wer wen wem wessen wie wo wann warum weshalb wieso wozu womit wodurch
wofuer woher wohin woran worauf woraus worin worueber wovon wieviel wieviele
an auf aus bei bis durch fuer gegen hinter in mit nach neben ohne seit ueber
um unter von vor waehrend wegen zu zwischen ab am ans aufs beim im ins vom
zum zur ausser entlang gegenueber innerhalb ausserhalb laut statt trotz per
pro
und oder aber denn sondern doch jedoch dass ob weil wenn als falls sofern
obwohl bevor nachdem damit sodass sowie sowohl weder noch entweder bzw
beziehungsweise
bin bist ist sind seid war warst waren wart gewesen sei seien waere waeren
haben habe hast hat habt hatte hattest hatten hattet gehabt haette haetten
werden werde wirst wird werdet wurde wurdest wurden wurdet geworden worden
wuerde wuerden
koennen kann kannst koennt konnte konnten koennte koennten
muessen muss musst muesst musste mussten muesste muessten
sollen soll sollst sollt sollte sollten wollen will willst wollt wollte
wollten
duerfen darf darfst duerft durfte durften duerfte duerften
moegen mag magst moegt mochte mochten moechte moechten moechtest
gibt gab mache machen macht tun tue tut
nicht nie niemals auch nur schon bereits sehr mehr weniger viel viele vielen
wenig wenige so dann da hier dort heute jetzt immer oft mal einmal eben halt
ja nein eigentlich ueberhaupt genau etwa ungefaehr circa ca ganz gar zwar
bitte danke gerne vielleicht wohl eher fast kaum bloss lediglich ausserdem
zudem daher deshalb deswegen darum also somit dabei dafuer dagegen danach
daran darauf daraus darin darueber darunter davon davor dazu dadurch hierzu
hierfuer wobei
andere anderen anderer anderes anderem anders
a an the and or but if then else of on in at by for from with without to
into onto over under about as is are was were be been being am do does did
done doing have has had having will would shall should can could may might
must no nor so than that this these those there here it its you he she
we they me him her them my your his our their what which whom whose when
where why how any both each few more other some such only own
too very just now after before between during through against while because
until above below again further once also off out up down
""".split())
# wortform/v1 — Endungen in fester Reihenfolge, je mit der Mindestlänge des
# verbleibenden Stamms. '-er' und '-em' verlangen vier Zeichen, sonst wird aus
# 'andere' über 'ander' ein 'and'.
WORTFORM_ENDUNGEN = (("en", 3), ("em", 4), ("er", 4), ("es", 3),
("e", 3), ("n", 3), ("s", 3))
# Ein Plural- oder Genitiv-s wird nur nach diesen Konsonanten entfernt. Ohne
# die Einschränkung würde aus 'Prozess' ein 'Proze' und aus 'Status' ein
# 'Statu'.
WORTFORM_S_VORGAENGER = frozenset("bcdfghklmnprtvw")
class RollbackIncompleteError(RuntimeError):
"""Mindestens ein Release-Ziel konnte nicht wiederhergestellt werden."""
class BudgetUeberschritten(OSError):
"""Ein gezähltes Budget eines Baumlaufs ist überschritten.
Unterklasse von OSError, damit jeder bestehende Aufrufer unverändert
fail-closed abbricht. Der eigene Typ trennt „zu groß" von „nicht lesbar":
nur so kann der externe Query-Pfad ``budget_exceeded`` melden, statt beide
Ursachen in einem Zustand zu vermengen.
"""
class AbrufbudgetErschoepft(Exception):
"""Die gezählten Netzabrufe dieser Abfrage sind aufgebraucht.
Bewusst KEINE OSError: kein allgemeiner Fehlerzweig darf das Budget als
gewöhnlichen Lesefehler verschlucken. Der Aufrufer zählt die übrigen
Dokumente als Lücke aus einem eigenen Grund.
"""
# ---------------------------------------------------------------- Hilfen
def rel(p: Path) -> str:
"""Lexikalischer, portabler Pfad innerhalb des Tresors."""
return Path(os.path.abspath(p)).relative_to(ROOT).as_posix()
def read(p: Path) -> str:
return p.read_text(encoding="utf-8")
def _plain_text(value, field, errors, *, maximum=500, allow_empty=False):
"""Kompakten, einzeiligen Metadatenwert validieren."""
if not isinstance(value, str):
errors.append(f"{field}: Text erwartet")
return False
if (not allow_empty and not value.strip()) or value != value.strip():
errors.append(f"{field}: leer oder mit Rand-Leerzeichen")
return False
if len(value) > maximum:
errors.append(f"{field}: länger als {maximum} Zeichen")
return False
if any(ord(char) < 32 or ord(char) == 127 for char in value):
errors.append(f"{field}: Steuerzeichen/Zeilenumbrüche sind verboten")
return False
return True
def _iso_date(value):
"""Kalendergültiges JJJJ-MM-TT oder None.
Das Format allein genügt nicht: '2026-02-31' passiert DATE_RE, ist aber
kein Datum. Rückgabe ist das date-Objekt, damit Aufrufer vergleichen
können, ohne ein zweites Mal zu parsen.
"""
text = str(value)
if not DATE_RE.match(text):
return None
try:
return date.fromisoformat(text)
except ValueError:
return None
def _trust_tier(actor):
"""Trust-Tier nach OKF v0.2 §5.3 ableiten, nie speichern.
Die isinstance-Wache ist nicht kosmetisch: cmd_stats läuft bewusst auch
auf einem roten Bestand, und ein Frontmatter mit Liste statt Text hätte
dort einen rohen Traceback erzeugt, also genau dann, wenn man die
Diagnose braucht.
"""
if not isinstance(actor, str) or not actor:
return TIER_UNVERIFIED
return TIER_HUMAN if actor.startswith("mensch:") else TIER_MACHINE
def _strict_json_pairs(pairs):
"""JSON-Objekte mit doppelten Schlüsseln fail-closed ablehnen."""
result = {}
for key, value in pairs:
if key in result:
raise ValueError(f"doppelter JSON-Schlüssel {key!r}")
result[key] = value
return result
def _reject_json_constant(value):
raise ValueError(f"nicht standardkonstante JSON-Zahl {value!r}")
def _load_strict_json(path: Path, label: str, errors):
"""Kleine JSON-Datei sicher, größenbegrenzt und ohne Duplicate Keys lesen."""
if not _safe_regular_file(path):
errors.append(f"{label}: fehlt oder ist keine sichere reguläre Datei")
return None
try:
flags = (
os.O_RDONLY | getattr(os, "O_BINARY", 0)
| getattr(os, "O_NOFOLLOW", 0)
)
fd = os.open(str(path), flags)
try:
status = os.fstat(fd)
if not stat.S_ISREG(status.st_mode) or status.st_nlink != 1:
raise OSError("keine einfach verlinkte reguläre Datei")
chunks, total = [], 0
while True:
chunk = os.read(fd, min(65536, MAX_JSON_BYTES + 1 - total))
if not chunk:
break
chunks.append(chunk)
total += len(chunk)
if total > MAX_JSON_BYTES:
raise ValueError(f"größer als {MAX_JSON_BYTES} Bytes")
source = b"".join(chunks).decode("utf-8")
finally:
os.close(fd)
return json.loads(
source,
object_pairs_hook=_strict_json_pairs,
parse_constant=_reject_json_constant,
)
except (OSError, UnicodeError, json.JSONDecodeError, ValueError) as exc:
errors.append(f"{label}: ungültiges JSON — {exc}")
return None
def _exact_keys(value, required, optional, field, errors):
if not isinstance(value, dict):
errors.append(f"{field}: JSON-Objekt erwartet")
return False
missing = sorted(set(required) - set(value))
unknown = sorted(set(value) - set(required) - set(optional))
if missing:
errors.append(f"{field}: Pflichtfelder fehlen {missing}")
if unknown:
errors.append(f"{field}: unbekannte Felder {unknown}")
return not missing and not unknown
def _read_prefix(path: Path, size=16):
"""Dateisignatur ohne Link-Folgen lesen."""
if _is_path_alias(path):
raise OSError(f"{path}: Link statt regulärer Datei")
flags = os.O_RDONLY | getattr(os, "O_BINARY", 0) | getattr(os, "O_NOFOLLOW", 0)
fd = os.open(str(path), flags)
try:
status = os.fstat(fd)
if not stat.S_ISREG(status.st_mode) or status.st_nlink != 1:
raise OSError(f"{path}: keine einfach verlinkte reguläre Datei")
return os.read(fd, size)
finally:
os.close(fd)
def _detected_media_type(path: Path):
try:
prefix = _read_prefix(path, 64 * 1024)
except OSError:
return None
if prefix.startswith(b"\x89PNG\r\n\x1a\n"):
return "image/png"
if prefix.startswith(b"\xff\xd8\xff"):
return "image/jpeg"
if prefix.startswith((b"GIF87a", b"GIF89a")):
return "image/gif"
if len(prefix) >= 12 and prefix[:4] == b"RIFF" and prefix[8:12] == b"WEBP":
return "image/webp"
if prefix.startswith((b"II*\x00", b"MM\x00*")):
return "image/tiff"
if prefix.startswith(b"%PDF-"):
return "application/pdf"
if prefix.startswith(b"BM"):
return "image/bmp"
if prefix.startswith(b"\x00\x00\x01\x00"):
return "image/x-icon"
if len(prefix) >= 12 and prefix[4:8] == b"ftyp":
brand = prefix[8:12]
if brand in {b"avif", b"avis"}:
return "image/avif"
if brand in {b"heic", b"heix", b"hevc", b"hevx", b"mif1", b"msf1"}:
return "image/heif"
text_prefix = prefix.lstrip(b"\xef\xbb\xbf \t\r\n").lower()
# Ein SVG darf sich nicht durch XML-Prolog oder führende Kommentare als
# Textquelle tarnen. Der Parser bleibt bewusst klein und fail-closed:
# ein innerhalb von 64 KiB nicht abgeschlossenes Markup-Preamble wird
# ebenfalls als aktive XML-/SVG-Signatur behandelt.
while text_prefix.startswith((b"<!--", b"<?")):
if text_prefix.startswith(b"<!--"):
end = text_prefix.find(b"-->")
marker_size = 3
else:
end = text_prefix.find(b"?>")
marker_size = 2
if end < 0:
return "image/svg+xml"
text_prefix = text_prefix[end + marker_size:].lstrip(b" \t\r\n")
if text_prefix.startswith(b"<!doctype") and b"svg" in text_prefix[:512]:
return "image/svg+xml"
if text_prefix.startswith(b"<svg"):
return "image/svg+xml"
return None
def _media_signature_matches(path: Path, media_type: str) -> bool:
return _detected_media_type(path) == media_type
def _is_path_alias(p: Path) -> bool:
"""Symlink oder Windows-Reparse-Point/Junction erkennen, ohne zu folgen."""
try:
status = os.lstat(str(p))
except OSError:
return False
reparse_flag = getattr(stat, "FILE_ATTRIBUTE_REPARSE_POINT", 0x400)
attributes = getattr(status, "st_file_attributes", 0)
return stat.S_ISLNK(status.st_mode) or bool(attributes & reparse_flag)
def sha256_file(p: Path) -> str:
"""Reguläre Datei hashen, ohne einem Symlink zu folgen."""
if _is_path_alias(p):
raise OSError(f"{p}: Symlinks/Reparse-Points werden nicht gehasht")
# O_NONBLOCK: ein FIFO unter einem Dateinamen öffnete sonst blockierend
# und hielt den Prozess an, bis jemand hineinschreibt. So kehrt open
# sofort zurück, und die S_ISREG-Prüfung lehnt es ab. Auf regulären
# Dateien hat das Flag keine Wirkung.
flags = (os.O_RDONLY | getattr(os, "O_BINARY", 0)
| getattr(os, "O_NOFOLLOW", 0) | getattr(os, "O_NONBLOCK", 0))
fd = os.open(str(p), flags)
h = hashlib.sha256()
try:
if not stat.S_ISREG(os.fstat(fd).st_mode):
raise OSError(f"{p}: keine reguläre Datei")
with os.fdopen(fd, "rb", closefd=False) as f:
for chunk in iter(lambda: f.read(65536), b""):
h.update(chunk)
finally:
os.close(fd)
return h.hexdigest()
def _sha256_bytes(data: bytes) -> str:
return hashlib.sha256(data).hexdigest()
def _resolved_within(p: Path, basis: Path) -> bool:
"""Auch über Symlinks nur Pfade innerhalb von ``basis`` zulassen."""
try:
p.resolve(strict=False).relative_to(basis.resolve(strict=True))
return True
except (OSError, RuntimeError, ValueError):
return False
def _first_alias_component(p: Path, basis: Path):
"""Ersten Symlink/Reparse-Point zwischen ``basis`` und ``p`` liefern.
Ein Pfad außerhalb von ``basis`` gilt als Alias — das ist die Sperre, die
verhindert, dass Tresorhelfer versehentlich fremde Bäume akzeptieren.
Externe Wurzeln bekommen deshalb eigene Aufrufe mit eigener Basis, statt
dass diese Prüfung aufgeweicht wird.
"""
try:
teile = Path(os.path.abspath(p)).relative_to(basis).parts
except ValueError:
return p
aktuell = basis
for teil in teile:
aktuell = aktuell / teil
if _is_path_alias(aktuell):
return aktuell
return None
def _first_symlink_component(p: Path):
"""Ersten Symlink/Reparse-Point zwischen Tresorwurzel und ``p`` liefern."""
return _first_alias_component(p, ROOT)
def _safe_regular_file_within(p: Path, basis: Path) -> bool:
"""Nur echte, einfach verlinkte Dateien unterhalb von ``basis``."""
if _first_alias_component(p, basis) is not None or not _resolved_within(p, basis):
return False
try:
status = os.lstat(str(p))
except OSError:
return False
return stat.S_ISREG(status.st_mode) and status.st_nlink == 1
def _safe_regular_file(p: Path) -> bool:
"""Nur echte, einfach verlinkte Dateien innerhalb des Tresors akzeptieren."""
return _safe_regular_file_within(p, ROOT)
def _safe_directory_within(p: Path, basis: Path) -> bool:
"""Nur echte Verzeichnisse ohne Alias-Komponente unterhalb von ``basis``."""
if _first_alias_component(p, basis) is not None or not _resolved_within(p, basis):
return False
try:
return stat.S_ISDIR(os.lstat(str(p)).st_mode)
except OSError:
return False
def _safe_directory(p: Path) -> bool:
"""Nur echte Verzeichnisse ohne Symlink-Komponente akzeptieren."""
return _safe_directory_within(p, ROOT)
def _safe_relative_path(basis: Path, raw: str):
"""Portablen relativen Pfad unter ``basis`` auflösen.
Rückgabe: ``(pfad, None)`` oder ``(None, fehlergrund)``.
"""
original = str(raw)
wert = original.strip()
if not wert:
return None, "Pfad ist leer"
if wert != original:
return None, "führende oder abschließende Leerzeichen sind verboten"
if any(ord(zeichen) < 32 or ord(zeichen) == 127 for zeichen in wert):
return None, "Steuerzeichen sind in portablen Pfaden verboten"
if "\\" in wert:
return None, "Backslashes sind nicht portabel; '/' verwenden"
raw_pfad = Path(wert)
if (raw_pfad.is_absolute() or wert.startswith(("/", "\\"))
or re.match(r"^[A-Za-z]:[\\/]", wert)):
return None, "absolute Pfade sind verboten"
if ".." in raw_pfad.parts:
return None, "'..' ist in Tresor-Pfaden verboten"
kandidat = basis / raw_pfad
if not _resolved_within(kandidat, basis):
return None, "Pfad oder Symlink zeigt aus dem erlaubten Bereich hinaus"
return kandidat, None
def _safe_output_target(p: Path):
"""Schreibziel und alle Eltern müssen echte Pfade im Tresor sein."""
try:
relativ = Path(os.path.abspath(p)).relative_to(ROOT)
except ValueError:
return False, "Schreibziel liegt außerhalb des Tresors"
symlink = _first_symlink_component(p)
if symlink is not None:
return False, f"Symlink im Schreibpfad {rel(symlink)!r}"
if not _resolved_within(p.parent, ROOT):
return False, "Elternpfad des Schreibziels zeigt aus dem Tresor hinaus"
if p.exists():
try:
status = os.lstat(str(p))
except OSError as exc:
return False, f"Schreibziel kann nicht geprüft werden: {exc}"
if not stat.S_ISREG(status.st_mode):
return False, "bestehendes Schreibziel ist keine reguläre Datei"
if status.st_nlink != 1:
return False, "Schreibziel ist mehrfach hart verlinkt"
return True, None
def _markdown_link_target(raw: str):
"""Ziel aus der unterstützten Markdown-Link-Untermenge lesen."""
wert = raw.strip()
if not wert:
return None, "leeres Linkziel"
rest = ""
if wert.startswith("<"):
ende = wert.find(">")
if ende < 0:
return None, "nicht geschlossenes '<...>'-Linkziel"
ziel, rest = wert[1:ende], wert[ende + 1:].strip()
else:
teile = wert.split(maxsplit=1)
ziel = teile[0]
rest = teile[1].strip() if len(teile) == 2 else ""
if rest:
gueltiger_titel = (
len(rest) >= 2
and ((rest[0] == rest[-1] and rest[0] in "\"'")
or (rest[0] == "(" and rest[-1] == ")"))
)
if not gueltiger_titel:
return None, "nicht unterstützte Linksyntax nach dem Ziel"
return ziel, None
def _quarantine_payloads():
"""Nicht freigegebene Dateien/Ordner in der Quarantäne."""
if not _safe_directory(QUARANTINE):
return [QUARANTINE]
return sorted(
(p for p in QUARANTINE.iterdir()
if not (p.name == "README.md" and _safe_regular_file(p))),
key=lambda p: p.name,
)
def _rel_zu(p: Path, basis: Path) -> str:
"""Lexikalischer, portabler Pfad relativ zu einer beliebigen Basis."""
return Path(os.path.abspath(p)).relative_to(basis).as_posix()
def _utf8_pfad(pfad: str) -> bool:
"""Ob ein Pfad als UTF-8 darstellbar ist.
Dateinamen aus Bytes ohne gültiges UTF-8 liefert das Betriebssystem als
Surrogate (``os.fsdecode``). Sie lassen sich weder in JSON-Ausgabe noch in
einen Hash zuverlässig schreiben und werden deshalb vorher abgelehnt.
"""
try:
pfad.encode("utf-8")
except UnicodeEncodeError:
return False
return True
def _walk_tree_no_links_within(start: Path, basis: Path, *, max_tiefe=None,
max_eintraege=None):
"""Deterministischer Baumlauf unterhalb von ``basis``, ohne Alias zu folgen.
``max_tiefe`` und ``max_eintraege`` sind gezählte Budgets, keine Zeitlimits:
ein Wall-Clock-Limit würde die Determinismus-Garantie brechen. Wird ein
Budget überschritten, bricht der Lauf fail-closed ab, statt ein
Teilergebnis zu liefern, das wie ein vollständiges aussieht.
"""
if not _safe_directory_within(start, basis):
return []
ergebnis, stapel, besucht = [], [(start, 0)], 0
while stapel:
ordner, tiefe = stapel.pop()
if max_tiefe is not None and tiefe > max_tiefe:
raise BudgetUeberschritten(
f"{_rel_zu(ordner, basis)}: Verzeichnistiefe über {max_tiefe}"
)
try:
with os.scandir(str(ordner)) as scan:
eintraege = sorted(scan, key=lambda e: e.name, reverse=True)
except OSError as exc:
raise OSError(
f"{_rel_zu(ordner, basis)}: Verzeichnis kann nicht gelesen "
f"werden — {exc}"
) from exc
for eintrag in eintraege:
p = Path(eintrag.path)
besucht += 1
if max_eintraege is not None and besucht > max_eintraege:
# Der Startpfad, nicht die Basis: beim fremden Tresor ist das
# knowledge/, und „." sagte niemandem, wo es zu viel ist.
raise BudgetUeberschritten(
f"{_rel_zu(start, basis) or '.'}: mehr als {max_eintraege} "
f"Verzeichniseinträge"
)
ergebnis.append(p)
try:
status = eintrag.stat(follow_symlinks=False)
except OSError as exc:
raise OSError(
f"{_rel_zu(p, basis)}: Verzeichniseintrag kann nicht "
f"geprüft werden — {exc}"
) from exc
reparse_flag = getattr(stat, "FILE_ATTRIBUTE_REPARSE_POINT", 0x400)
attributes = getattr(status, "st_file_attributes", 0)
alias = stat.S_ISLNK(status.st_mode) or bool(attributes & reparse_flag)
if stat.S_ISDIR(status.st_mode) and not alias:
stapel.append((p, tiefe + 1))
return sorted(ergebnis, key=lambda p: _rel_zu(p, basis))
def _walk_tree_no_links(start: Path):
"""Deterministischer Baumlauf, der Symlinks/Junctions nie rekursiv folgt."""
return _walk_tree_no_links_within(start, ROOT)
def _skill_symlinks():
"""Symlinks/Junctions sind im portablen Skill-Artefakt verboten."""
return [p for p in _walk_tree_no_links(ROOT) if _is_path_alias(p)]
def _skill_hardlinks():
"""Mehrfach hart verlinkte Dateien umgehen die Ordnergrenze."""
ergebnis = []
for p in _walk_tree_no_links(ROOT):
if _is_path_alias(p):
continue
try:
status = os.lstat(str(p))
if stat.S_ISREG(status.st_mode) and status.st_nlink != 1:
ergebnis.append(p)
except OSError:
continue
return sorted(ergebnis, key=lambda p: rel(p))
def _skill_fremdartefakte():
"""Dateiarten, die nicht in ein portables Wissensartefakt gehören.
Rückgabe: Liste (Pfad, Grund). Geprüft wird nur, was das Manifest
ohnehin abdeckt; Quarantäne-Payloads, Lock und Cache haben eigene
Prüfungen. Ein gesetztes Ausführungsbit ist immer ein Fehler: der Tresor
liefert Wissen aus, keinen ausführbaren Inhalt.
"""
ergebnis = []
for p in _walk_tree_no_links(ROOT):
if _is_path_alias(p) or not _tracked_path(p):
continue
try:
status = os.lstat(str(p))
except OSError:
continue
if not stat.S_ISREG(status.st_mode):
continue
suffix = p.suffix.lower()
if rel(p) == ENGINE_SCRIPT:
erlaubt, benennung = True, "Engine-Script"
elif suffix:
erlaubt = suffix in ARTEFAKT_SUFFIXE
benennung = f"Endung {suffix}"
else:
erlaubt = p.name in ARTEFAKT_DATEINAMEN
benennung = "Datei ohne Endung"
if not erlaubt:
ergebnis.append((p, f"{benennung} ist im Tresor nicht vorgesehen"))
elif status.st_mode & 0o111:
ergebnis.append((p, "Ausführungsbit ist gesetzt"))
return sorted(ergebnis, key=lambda eintrag: rel(eintrag[0]))
def _skill_geheimnisse():
"""Zugangsdaten in manifestierten Textdateien finden.
Rückgabe: Liste (Pfad, Zeilennummer, Formbeschreibung). Der Treffer selbst
wird nie ausgegeben — die Meldung soll das Geheimnis nicht in Log, CI-Ausgabe
oder Chatverlauf weitertragen. Medien werden nicht dekodiert (AD-07); die
Engine selbst ist ausgenommen, weil sie die Muster definiert.
"""
ergebnis = []
for p in _walk_tree_no_links(ROOT):
if (_is_path_alias(p) or not _tracked_path(p)
or p.suffix.lower() not in SECRET_SUFFIXE
or not _safe_regular_file(p)):
continue
try:
text = read(p)
except (OSError, UnicodeError):
# Nicht lesbarer Text fällt an anderer Stelle von validate auf.
continue
for nummer, zeile in enumerate(text.split("\n"), start=1):
treffer = next((t for t in SECRET_RE.finditer(zeile)
if not _secret_platzhalter(t.group(0))), None)
if treffer:
form = ("Zugangsdaten in URL" if "://" in treffer.group(0)
else f"Schlüsselform {treffer.group(0)[:4]}…")
ergebnis.append((p, nummer, form))
return sorted(ergebnis, key=lambda eintrag: (rel(eintrag[0]), eintrag[1]))
def iter_pages():
if not _safe_directory(KNOWLEDGE):
return []
return sorted(
(p for p in _walk_tree_no_links(KNOWLEDGE)
if p.suffix == ".md" and _safe_regular_file(p)),
key=lambda p: rel(p),
)
# ------------------------------------------- Parser (Profil-Untermenge)
def parse_frontmatter(text, quelle):
"""Flaches Frontmatter der Profil-Untermenge parsen.
Erlaubt: 'key: skalar', 'key: [a, b]' und mehrzeilige Listen
('key:' gefolgt von ' - wert'). Nichts Verschachteltes, bewusst,
damit genau EIN einfacher, prüfbarer Parser genügt.
Verschachtelung wird fail-closed abgelehnt und nicht toleriert. Ohne diese
Prüfung zog die Blockform ('key:' gefolgt von ' unter: wert') ihre
Unterschlüssel still ins Top-Level-Dictionary und machte den Wert zur
leeren Liste. Das war Strukturkorruption ohne Fehlermeldung.
Rückgabe: (dict, body, fehlerliste, body_offset in Dateizeilen)
"""
fehler = []
lines = text.split("\n")
if not lines or lines[0].rstrip("\r") != "---":
return {}, text, [f"{quelle}: kein Frontmatter (Datei muss mit '---' beginnen)"], 0
fm, i, ende = {}, 1, None
while i < len(lines):
line = lines[i]
# Der Terminator wird strikt geprüft. Ein eingerücktes '---' beendete
# den Block früher stillschweigend, weil strip() die Einrückung
# entfernt: alles danach landete im Body, und fehlten dabei nur
# optionale Felder, blieb validate grün und der Graph verlor Kanten.
if line.rstrip("\r") == "---":
ende = i
break
if not line.strip() or _ist_kommentarzeile(line):
i += 1
continue
if line != line.lstrip() and not line.startswith(" - "):
fehler.append(
f"{quelle}:{i + 1}: Einrückung außerhalb der Profil-Untermenge; "
f"verschachteltes Frontmatter ist nicht erlaubt: "
f"{line.strip()!r}")
i += 1
continue
if line.startswith(" - "):
fehler.append(f"{quelle}: Listenzeile ohne zugehörigen Schlüssel: {line.strip()!r}")
i += 1
continue
if ":" not in line:
fehler.append(f"{quelle}: Frontmatter-Zeile ohne ':' — {line.strip()!r}")
i += 1
continue
key, _, val = line.partition(":")
key, val = key.strip(), val.strip()
if key in fm:
fehler.append(f"{quelle}:{i + 1}: Frontmatter-Schlüssel {key!r} ist doppelt")
i += 1
continue
if val == "":
werte, j = [], i + 1
while j < len(lines) and lines[j].startswith(" - "):
werte.append(lines[j][4:].strip().strip('"').strip("'"))
j += 1
fm[key] = werte
i = j
continue
if val.startswith("[") and val.endswith("]"):
inner = val[1:-1].strip()
fm[key] = ([] if not inner else
[x.strip().strip('"').strip("'") for x in inner.split(",")])
else:
fm[key] = val.strip('"').strip("'")
i += 1
if ende is None:
return fm, "", [f"{quelle}: Frontmatter nicht geschlossen (zweites '---' fehlt)"], 0
return fm, "\n".join(lines[ende + 1:]), fehler, ende + 1
def parse_types():
"""schema/types.yaml (zweistufig, Profil-Untermenge) lesen.
Rückgabe: (typen: dict[name -> felder], relationstypen: liste, fehler)
"""
fehler = []
if not _safe_regular_file(TYPES):
return {}, [], [f"{rel(TYPES)}: fehlt oder ist keine reguläre Datei "
f"— Typ-Registry ist Pflicht"]
typen, reltypen, aktuell = {}, [], None
reltypen_gesehen = False
for n, line in enumerate(read(TYPES).split("\n"), 1):
if not line.strip() or line.lstrip().startswith("#"):
continue
if not line.startswith(" "):
if ":" not in line:
fehler.append(f"{rel(TYPES)}:{n}: Top-Level-Zeile ohne ':'")
aktuell = None
continue
key, _, val = line.partition(":")
key, val = key.strip(), val.strip()
if key == "_relationstypen":
if reltypen_gesehen:
fehler.append(f"{rel(TYPES)}:{n}: _relationstypen ist doppelt definiert")
reltypen_gesehen = True
if not (val.startswith("[") and val.endswith("]")):
fehler.append(f"{rel(TYPES)}:{n}: _relationstypen muss "
f"eine Inline-Liste '[a, b]' sein")
inner = ""
else:
inner = val[1:-1].strip()
reltypen = [x.strip() for x in inner.split(",") if x.strip()]
if len(reltypen) != len(set(reltypen)):
fehler.append(f"{rel(TYPES)}:{n}: doppelte Relationstypen")
for rtyp in reltypen:
if not re.match(r"^[a-z][a-z0-9_]*$", rtyp):
fehler.append(f"{rel(TYPES)}:{n}: ungültiger Relationstyp {rtyp!r}")
aktuell = None
elif val == "":
if not re.match(r"^[a-z][a-z0-9_-]*$", key):
fehler.append(f"{rel(TYPES)}:{n}: ungültiger Typname {key!r}")
aktuell = None
continue
if key in typen:
fehler.append(f"{rel(TYPES)}:{n}: Typ {key!r} ist doppelt definiert")
aktuell = None
continue
aktuell = key
typen[aktuell] = {}
else:
fehler.append(f"{rel(TYPES)}:{n}: Top-Level braucht 'typname:' ohne Wert")
elif line.startswith(" ") and aktuell:
if ":" not in line.strip():
fehler.append(f"{rel(TYPES)}:{n}: Typfeld ohne ':'")
continue
key, _, val = line.strip().partition(":")
key = key.strip()
if key in typen[aktuell]:
fehler.append(f"{rel(TYPES)}:{n}: Feld {key!r} in Typ {aktuell!r} ist doppelt")
continue
typen[aktuell][key] = val.strip().strip('"')
else:
fehler.append(f"{rel(TYPES)}:{n}: Einrückung außerhalb der Profil-Untermenge")
if not typen:
fehler.append(f"{rel(TYPES)}: keine Typen registriert — fail-closed")
if not reltypen_gesehen or not reltypen:
fehler.append(f"{rel(TYPES)}: _relationstypen fehlt oder ist leer — fail-closed")
for typ, felder in sorted(typen.items()):
fehlend = sorted(TYPE_REQUIRED_FIELDS - set(felder))
unbekannt = sorted(set(felder) - TYPE_REQUIRED_FIELDS)
leer = sorted(k for k in TYPE_REQUIRED_FIELDS & set(felder) if not felder[k].strip())
if fehlend:
fehler.append(f"{rel(TYPES)}: Typ {typ!r} ohne Pflichtfelder {fehlend}")
if unbekannt:
fehler.append(f"{rel(TYPES)}: Typ {typ!r} mit unbekannten Feldern {unbekannt}")
if leer:
fehler.append(f"{rel(TYPES)}: Typ {typ!r} mit leeren Pflichtfeldern {leer}")
return typen, reltypen, fehler
def _retrieval_norm(value):
"""Versionierte Unicode-Normalisierung nur für Hybrid-Retrieval."""
text = unicodedata.normalize("NFKC", str(value)).casefold()
text = (text.replace("ä", "ae").replace("ö", "oe")
.replace("ü", "ue").replace("ß", "ss"))
text = "".join(char if char.isalnum() else " " for char in text)
return re.sub(r"\s+", " ", text).strip()
# Stoppwörter durchlaufen dieselbe Normalisierung wie jede Anfrage. In v1
# stand „für" roh in der Liste und wurde mit dem schon normalisierten Token
# „fuer" verglichen — das Wort wirkte nie als Stoppwort.
RETRIEVAL_STOPWORDS_NORM = frozenset(
_retrieval_norm(wort) for wort in RETRIEVAL_STOPWORDS
)
def _retrieval_tokens(value):
return tuple(
token for token in _retrieval_norm(value).split()
if token not in RETRIEVAL_STOPWORDS_NORM
and (len(token) >= 2 or token.isdigit())
)
def _phrase_present(haystack, needle):
"""Normalisierte Phrase nur an Token-Grenzen finden."""
return bool(needle) and f" {needle} " in f" {haystack} "
# --------------------------------------------------------- wortform/v1
#
# Drei Abgleichsstufen, streng in dieser Reihenfolge und jede mit eigenem
# Grund im Ergebnis: 'token' (exakt), 'stem' (dieselbe Wortform-Familie) und
# 'compound' (Kopf oder Schwanz eines Kompositums). Keine der drei rät eine
# Bedeutung. "feuchte Wände" findet auch danach keinen "Schimmelbefall" — das
# leistet erst die Vollsichtung, in der das Modell jeden Claim liest.
WORT_RE = re.compile(r"[^\W_]+")
def _kuerzel_tokens(text):
"""Normalisierte Tokens der Wörter, die in Großbuchstaben geschrieben sind.
"IT", "EU", "AG": nach casefold wären das 'it', 'eu', 'ag', und das erste
ist ein englisches Funktionswort. Erkannt wird eine Abkürzung nur dort, wo
die Schreibung etwas aussagt: in gemischt geschriebenem Text oder als
einzelnes Wort. Wer einen ganzen Satz groß schreibt, meint keine
Abkürzungen.
"""
woerter = WORT_RE.findall(text)
if len(woerter) > 1 and text == text.upper():
return frozenset()
gefunden = set()
for wort in woerter:
if len(wort) >= 2 and wort.isupper():
gefunden.update(_retrieval_norm(wort).split())
return gefunden
def _lokale_tokens(value):
"""Tokens für das lokale Ranking, mit der Stoppwortliste in alter Form.
Die Normalisierung der Stoppwörter (seit extern-zweistufig/v2) gilt für die
externe Suche. Lokal sortiert FUNKTIONSWOERTER die Funktionswörter aus; die
alte Filterung bleibt, damit hybrid-local/v4 bytegleich bleibt. Ein
großgeschriebenes „FÜR" in gemischt geschriebenem Text ist dort, wie jedes
Wort in Großbuchstaben, ein Kürzel.
"""
return tuple(
token for token in _retrieval_norm(value).split()
if token not in RETRIEVAL_STOPWORDS and (len(token) >= 2 or token.isdigit())
)
# Funktionswörter, die großgeschrieben ein Substantiv sind ("die Waren",
# "Soll und Haben", "die Würde"). Bewusst eine geschlossene Liste: Eine
# allgemeine Regel "groß mitten im Satz" machte jede Titelschreibung, jede
# ganz groß geschriebene Frage und jeden nicht erkannten Satzanfang zum
# Begriff, also gerade die Rauschtreffer, die v3 abschafft.
HOMOGRAPHE_SUBSTANTIVE = frozenset(
"waren soll haben macht mal wuerde sein bitte halt laut tun muss nichts "
"wohl".split())
# Nach diesen Zeichen beginnt ein Satz (auch nach Doppelpunkt, Semikolon
# und Gedankenstrich), ebenso nach einer Aufzählungsmarke ("1)", "a)", "-").
SATZZEICHEN_VOR_SATZANFANG = ".!?…:;–—"
AUFZAEHLUNG_VOR_SATZANFANG_RE = re.compile(
r"(?:^|\s)(?:\d{1,3}[.)]|[A-Za-z][)]|[-*•–—])$")
# Ein Homograph am Satzanfang ist nur dann ein Substantiv, wenn er für
# sich steht ("Begriffsfrage: Waren – was …", "Waren?"). Folgt ein Wort,
# ist er dort meist das Verb eines Satzes ("Frage: Muss ich …", "Muss bei
# Auszug …", "Soll oder muss …"); eine Wortgruppe wie "Würde des Menschen"
# geht dabei verloren (notes/dead-ends.md).
SATZZEICHEN_NACH_ALLEINSTEHEND = "–—-,;:.!?…"
# Die Pronomen der Anrede sind in Großbuchstaben kein Kürzel ("Können SIE
# das?"), anders als "IT". Nur für die externe Suche; das lokale Ranking
# bleibt bytegleich.
ANREDE_PRONOMEN = frozenset(
"sie ihnen ihre ihrem ihren ihrer ihres du dich dir dein deine deinem "
"deinen deiner deines euch euer eure eurem euren eurer eures".split())
def _versalien(text):
"""Ist ein Text aus mehreren Wörtern ganz groß geschrieben? Ein "ß"
zählt dabei als groß ("STRAßE"), denn es hat keine Großform in str."""
gross = text.replace("ß", "SS")
return len(WORT_RE.findall(text)) > 1 and gross == gross.upper()
def _titelschreibung(text):
"""Steht ein Text aus mindestens drei Wörtern in Titelschreibung?
Jedes Wort beginnt groß, und mitten im Text auch ein Funktionswort, das
kein Homograph der Liste ist ("Wann Muss Der Mieter …"). Eine Folge
großgeschriebener Substantive ist im Deutschen keine Titelschreibung,
sondern eine Stichwortfrage ("Zollgebühren Waren China")."""
woerter = [wort for wort in WORT_RE.findall(text) if wort[:1].isalpha()]
if len(woerter) < 3 or not all(wort[:1].isupper() for wort in woerter):
return False
return any(token in FUNKTIONSWOERTER
and token not in HOMOGRAPHE_SUBSTANTIVE
for wort in woerter[1:]
for token in _retrieval_norm(wort).split())
def _sachwoerter_gross(text):
"""Homographe, die großgeschrieben mitten im Satz stehen.
Im Deutschen ist ein solches Wort ein Substantiv und damit ein Sachwort
("Was sind Waren?"). Am Satzanfang sagt die Großschreibung nichts, außer
das Wort steht für sich; in einer Frage in Versalien oder in
Titelschreibung sagt sie nie etwas. Der Text wird vorher normalisiert,
damit eine zerlegte Schreibung (NFD) das Wort nicht teilt."""
text = unicodedata.normalize("NFKC", text)
if _versalien(text) or _titelschreibung(text):
return set()
gross = set()
for fund in WORT_RE.finditer(text):
wort = fund.group(0)
if not wort[:1].isupper():
continue
treffer = {token for token in _retrieval_norm(wort).split()
if token in HOMOGRAPHE_SUBSTANTIVE}
if not treffer:
continue
# Leerraum, Anführungszeichen und Klammern in einem Schritt: auch
# 'Frage. „Muss ich …“' beginnt einen Satz, und eine Aufzählungsmarke
# vor einem Anführungszeichen ('1) „Muss ich …“') zählt ebenso.
roh = text[:fund.start()].rstrip(" \t\r\n\"'„“”‚‘’»«")
davor = roh.rstrip(" \t\r\n\"'„“”‚‘’»«()[]")
if (not davor or davor[-1] in SATZZEICHEN_VOR_SATZANFANG
or AUFZAEHLUNG_VOR_SATZANFANG_RE.search(roh)):
danach = text[fund.end():].lstrip(" \t\"'“”‚‘’»«)]")
if danach and danach[0] not in SATZZEICHEN_NACH_ALLEINSTEHEND:
continue
gross.update(treffer)
return gross
def _anfragebegriffe(query):
"""Anfragebegriffe der externen Suche (seit extern-zweistufig/v3).
Die Tokens der Frage wie bisher (_retrieval_tokens), ohne die
Funktionswörter des lokalen Rankings. Es bleiben ein Kürzel in
Großbuchstaben ("IT", nicht aber die Pronomen der Anrede) und ein
Homograph, der großgeschrieben mitten im Satz steht ("Was sind Waren?").
Besteht die Frage nur aus Homographen ("Würde"), bleiben sie. Bleibt
nichts übrig, sucht die Frage nicht (invalid_query, kein
Negativbefund). Die Dokumentseite tokenisiert unverändert:
Katalogzahlen, Satzbestand und Fingerprint-Rezept hängen nicht an
dieser Liste. Normalisiert wird vorab (NFKC), damit eine zerlegte
Schreibung kein Wort teilt; _kuerzel_tokens selbst bleibt unverändert,
denn das lokale Ranking hängt daran."""
text = unicodedata.normalize("NFKC", str(query))
behalten = ((_kuerzel_tokens(text.replace("ß", "SS")) - ANREDE_PRONOMEN)
| _sachwoerter_gross(text))
tokens = _retrieval_tokens(text)
begriffe = tuple(token for token in tokens
if token not in FUNKTIONSWOERTER or token in behalten)
if not begriffe and all(wort in HOMOGRAPHE_SUBSTANTIVE
for wort in _retrieval_norm(text).split()):
# Nur Homographe ("Würde"): Jedes Token ist einer von ihnen.
begriffe = tokens
return begriffe
def _inhaltstokens(value):
"""Inhaltstragende Tokens des lokalen Rankings: ohne Funktionswörter."""
text = str(value)
kuerzel = _kuerzel_tokens(text)
return tuple(
token for token in _lokale_tokens(text)
if token not in FUNKTIONSWOERTER or token in kuerzel
)
def _wortform_flexion(stamm):
for _ in range(3):
for endung, minimum in WORTFORM_ENDUNGEN:
if (not stamm.endswith(endung)
or len(stamm) - len(endung) < minimum):
continue
if endung == "s" and stamm[-2] not in WORTFORM_S_VORGAENGER:
continue
stamm = stamm[:-len(endung)]
break
else:
break
return stamm
def _wortstamm(token):
"""Versionierter Schlüssel einer Wortform-Familie (wortform/v1).
Eingabe ist ein Token aus ``_retrieval_norm``. Die Umlaut-Digraphen
werden gefaltet, damit 'Wände' zu 'Wand' und 'Mängel' zu 'Mangel' findet;
danach fallen Flexionsendungen und einmalig '-ung', damit 'Prüfungen' zu
'prüfen' findet. Der Schlüssel ist kein Wort und wird nie ausgegeben, er
dient nur dem Vergleich — beide Seiten laufen durch dieselbe Funktion.
Bewusst NICHT geleistet: Partizipien ('geprüft'), finite Verbformen auf
'-t', unregelmäßige Formen ('gilt'/'gelten'), '-heit', '-keit', '-lich'.
Jede dieser Regeln brächte mehr Kollisionen als Treffer, und was hier
nicht trifft, landet als 'unmatched' sichtbar im Ergebnis.
"""
if len(token) < 4 or any(char.isdigit() for char in token):
return token
stamm = _wortform_flexion(
token.replace("ae", "a").replace("oe", "o").replace("ue", "u")
)
if stamm.endswith("ung") and len(stamm) - 3 >= 4:
stamm = _wortform_flexion(stamm[:-3])
return stamm
def _stamm_norm(value):
"""Wie ``_retrieval_norm``, aber wortweise auf den Wortstamm gebracht.
Funktionswörter bleiben stehen: nur so liegen die Wörter einer
mehrteiligen Phrase auf beiden Seiten an derselben Stelle.
"""
return " ".join(_wortstamm(wort) for wort in _retrieval_norm(value).split())
def _kompositum_teil(teile, ganze):
"""Ist eine Form aus ``teile`` Kopf oder Schwanz einer Form aus ``ganze``?
Geprüft wird nur am Wortanfang und am Wortende, und beide Seiten der
Nahtstelle brauchen mindestens ``KOMPOSITUM_MIN_TEIL`` Zeichen. Damit
findet 'Miete' die 'Mietminderung' und 'Nachweis' den 'Herkunftsnachweis'
(das Fugen-s zählt zum Rest), aber 'himmel' nie 'schimmel': der Rest 'sc'
ist kein Wortteil. Ein Wörterbuch gibt es nicht, also bleibt die Stufe
schwach gewichtet und zählt nie als verstandener Begriff.
"""
for teil in teile:
if len(teil) < KOMPOSITUM_MIN_TEIL:
continue
for ganz in ganze:
if len(ganz) - len(teil) < KOMPOSITUM_MIN_TEIL:
continue
if ganz.startswith(teil) or ganz.endswith(teil):
return True
return False
def _kompositum(links, rechts):
"""Symmetrischer Kompositumabgleich zweier Tokens über Token und Stamm."""
formen_links = {links, _wortstamm(links)}
formen_rechts = {rechts, _wortstamm(rechts)}
return (_kompositum_teil(formen_links, formen_rechts)
or _kompositum_teil(formen_rechts, formen_links))
# ------------------------------------------------- satzsegmentierung/v1
#
# Der Satzindex ist Teil eines Ankers, also braucht die Zerlegung einen
# versionierten, deterministischen Algorithmus. Abkürzungen, nach denen ein
# Punkt kein Satzende ist. Ohne diese Liste zerlegte 'Das Profil nutzt z. B.
# flache Listen. Danach folgt mehr.' zu 'Das Profil nutzt z.' — und diese
# Beschreibung landet gleich zweimal im Bundle, im Frontmatter und im
# Domänen-Index.
SATZ_ABKUERZUNGEN = {
"z", "b", "u", "a", "d", "h", "vgl", "bzw", "ca", "etc", "ff", "abs",
"nr", "bspw", "ggf", "evtl", "inkl", "exkl", "max", "min", "sog", "usw",
"s", "vs", "dr", "prof", "ebd", "bzgl", "o",
"art", "lit", "rn", "bd", "hrsg", "aufl", "approx", "resp", "no", "fig",
"pp", "cf", "e", "i", "g",
}
SATZENDE_RE = re.compile(r"([.!?])\s")
CODE_FENCE_RE = re.compile(r"^\s{0,3}(?:```|~~~)")
ATX_RE = re.compile(r"^\s{0,3}#{1,6}\s")
LIST_RE = re.compile(r"^\s*(?:[-*+]\s|\d+[.)]\s)")
QUOTE_RE = re.compile(r"^\s{0,3}>")
TABLE_RE = re.compile(r"^\s*\|")
def _satz_norm(text):
"""Normalisierung zum Zitieren: NFC, Whitespace kollabiert, getrimmt.
Bewusst NFC und nicht das NFKC aus ``_retrieval_norm``: NFKC faltet
Ligaturen und Formatzeichen und verändert damit den *Wortlaut*. Für
Matching ist das richtig, für ein Zitat ist es falsch. Zwei
Normalisierungen, zwei Zwecke, beide versioniert.
"""
return re.sub(r"\s+", " ", unicodedata.normalize("NFC", str(text))).strip()
def _satz_digest(text):
"""SHA-256 über den normalisierten Satz — macht den Anker selbstprüfend."""
return _sha256_bytes(_satz_norm(text).encode("utf-8"))
SATZ_TRENNER_RE = re.compile(r"[\s(]")
def _letztes_wort(text, ende, anfang=0):
"""Das Wort direkt vor ``ende`` — genau ``re.split(r"[\\s(]", …)[-1]``.
Rückwärts gesucht, statt den Kopf seit dem letzten Satzende jedes Mal neu
zu zerlegen: In einem Absatz voller Abkürzungen wuchs dieser Kopf mit
jedem Punkt, und jede Prüfung zerlegte ihn von vorn — quadratische
Laufzeit, für ein pathologisches Dokument von 1 MiB über eine Stunde.
Rückwärts endet jede Suche spätestens am Leerzeichen hinter dem vorigen
Satzzeichen, und das Ganze bleibt linear.
"""
i = ende
while i > anfang and not SATZ_TRENNER_RE.match(text, i - 1):
i -= 1
return text[i:ende]
def _wort_beendet_satz(letztes):
"""Ob ein Punkt nach diesem Wort einen Satz beendet."""
letztes = letztes.strip("„»‚'\"")
if letztes.lower() in SATZ_ABKUERZUNGEN or len(letztes) == 1:
return False
if letztes.isdigit() or re.fullmatch(r"[§]?\d+", letztes):
return False
# Dezimalzahlen und Versionsbezeichner: 'v0.2', '3.14', '1.2.0'
return not re.search(r"\d$", letztes)
def _ist_satzende(kopf):
"""Ob der Punkt am Ende von ``kopf`` wirklich einen Satz beendet."""
return _wort_beendet_satz(_letztes_wort(kopf, len(kopf)))
def _bloecke(text):
"""Markdown in Blöcke zerlegen; Frontmatter und Code-Fences fallen weg.
Beides enthält keine Sätze und würde sonst die Indizes verschieben.
"""
zeilen = str(text).replace("\r\n", "\n").replace("\r", "\n").split("\n")
start = 0
if zeilen and zeilen[0].strip() == "---":
for i in range(1, len(zeilen)):
if zeilen[i].strip() == "---":
start = i + 1
break
bloecke, puffer, art, im_code = [], [], "absatz", False
def abschliessen():
if puffer:
inhalt = " ".join(teil.strip() for teil in puffer if teil.strip())
if inhalt:
bloecke.append((art, inhalt))
puffer.clear()
for zeile in zeilen[start:]:
if CODE_FENCE_RE.match(zeile):
abschliessen()
im_code = not im_code
continue
if im_code:
continue
if not zeile.strip():
abschliessen()
art = "absatz"
continue
if ATX_RE.match(zeile):
abschliessen()
bloecke.append(("ueberschrift", zeile.lstrip("# \t").strip()))
art = "absatz"
continue
if TABLE_RE.match(zeile):
abschliessen()
for zelle in zeile.strip().strip("|").split("|"):
if zelle.strip() and not re.fullmatch(r"[\s:-]+", zelle):
bloecke.append(("tabellenzelle", zelle.strip()))
art = "absatz"
continue
if LIST_RE.match(zeile):
abschliessen()
art = "listenpunkt"
puffer.append(LIST_RE.sub("", zeile, count=1))
continue
if QUOTE_RE.match(zeile):
abschliessen()
art = "zitat"
puffer.append(QUOTE_RE.sub("", zeile, count=1))
continue
puffer.append(zeile)
abschliessen()
return bloecke
def _saetze(text):
"""Sätze eines Markdown-Textes als ``(index, blockart, satz)``.
Ein Satz überschreitet nie eine Blockgrenze: Absatz, Listenpunkt,
Tabellenzelle, Überschrift und Zitat beenden ihn immer.
"""
ergebnis, index = [], 0
for art, inhalt in _bloecke(text):
pos = 0
for treffer in SATZENDE_RE.finditer(inhalt):
# Geschnitten wird erst, wenn der Satz wirklich endet — ein
# Schnitt je Kandidat wäre wieder quadratisch.
if not _wort_beendet_satz(
_letztes_wort(inhalt, treffer.start(), pos)):
continue
satz = _satz_norm(inhalt[pos:treffer.start()] + treffer.group(1))
if satz:
index += 1
ergebnis.append((index, art, satz))
pos = treffer.end()
rest = _satz_norm(inhalt[pos:])
if rest:
index += 1
ergebnis.append((index, art, rest))
return ergebnis
def parse_concepts():
"""Strikte, beleggebundene Begriffswelten-Registry lesen."""
errors = []
data = _load_strict_json(CONCEPTS, rel(CONCEPTS), errors)
if data is None:
return {}, {}, errors
if not _exact_keys(
data, {"schema", "worlds", "concepts"}, set(),
rel(CONCEPTS), errors):
return {}, {}, errors
if data.get("schema") != CONCEPT_SCHEMA:
errors.append(
f"{rel(CONCEPTS)}: schema muss {CONCEPT_SCHEMA!r} sein"
)
worlds_raw = data.get("worlds")
concepts_raw = data.get("concepts")
if not isinstance(worlds_raw, list):
errors.append(f"{rel(CONCEPTS)}.worlds: Liste erwartet")
worlds_raw = []
if not isinstance(concepts_raw, list):
errors.append(f"{rel(CONCEPTS)}.concepts: Liste erwartet")
concepts_raw = []
if len(worlds_raw) > 128:
errors.append(f"{rel(CONCEPTS)}.worlds: höchstens 128 Einträge")
if len(concepts_raw) > 10000:
errors.append(f"{rel(CONCEPTS)}.concepts: höchstens 10000 Einträge")
worlds = {}
for index, item in enumerate(worlds_raw, 1):
field = f"{rel(CONCEPTS)}.worlds[{index}]"
if not _exact_keys(
item, {"id", "name", "description"}, set(), field, errors):
continue
wid = item.get("id")
if not isinstance(wid, str) or not WORLD_ID_RE.fullmatch(wid):
errors.append(f"{field}.id: erwartet BW-nnnn")
continue
if wid in worlds:
errors.append(f"{field}.id: Begriffswelt-ID {wid} ist doppelt")
continue
_plain_text(item.get("name"), f"{field}.name", errors, maximum=120)
_plain_text(
item.get("description"), f"{field}.description", errors, maximum=500
)
worlds[wid] = item
concepts = {}
required = {
"id", "world", "preferred", "aliases", "broader", "related",
"definition_claim",
}
for index, item in enumerate(concepts_raw, 1):
field = f"{rel(CONCEPTS)}.concepts[{index}]"
if not _exact_keys(item, required, set(), field, errors):
continue
cid = item.get("id")
if not isinstance(cid, str) or not CONCEPT_ID_RE.fullmatch(cid):
errors.append(f"{field}.id: erwartet B-nnnn")
continue
if cid in concepts:
errors.append(f"{field}.id: Begriff-ID {cid} ist doppelt")
continue
world = item.get("world")
if (not isinstance(world, str)
or not WORLD_ID_RE.fullmatch(world)
or world not in worlds):
errors.append(f"{field}.world: unbekannte Begriffswelt {world!r}")
if _plain_text(
item.get("preferred"), f"{field}.preferred", errors, maximum=160
):
# Begriffslabels wandern in Query-Ausgabe und Export. Sie waren
# bisher schwächer geprüft als Claim-Text, obwohl sie denselben Weg
# nach außen nehmen.
if PROMPT_INJECTION_RE.search(item["preferred"]):
errors.append(
f"{field}.preferred: enthält eine offensichtliche "
f"Instruktionssignatur")
definition_claim = item.get("definition_claim")
if (not isinstance(definition_claim, str)
or not CID_RE.fullmatch(definition_claim)):
errors.append(f"{field}.definition_claim: erwartet C-nnnn")
for list_name in ("aliases", "broader", "related"):
values = item.get(list_name)
if not isinstance(values, list):
errors.append(f"{field}.{list_name}: Liste erwartet")
item[list_name] = []
continue
if len(values) > 32:
errors.append(f"{field}.{list_name}: höchstens 32 Einträge")
if len(values) != len(set(
value for value in values if isinstance(value, str))):
errors.append(f"{field}.{list_name}: doppelte Einträge")
for number, value in enumerate(values, 1):
value_field = f"{field}.{list_name}[{number}]"
if list_name == "aliases":
if (_plain_text(value, value_field, errors, maximum=160)
and PROMPT_INJECTION_RE.search(value)):
errors.append(
f"{value_field}: enthält eine offensichtliche "
f"Instruktionssignatur")
elif not isinstance(value, str) or not CONCEPT_ID_RE.fullmatch(value):
errors.append(f"{value_field}: erwartet B-nnnn")
concepts[cid] = item
labels_by_world = {}
for cid, concept in sorted(concepts.items()):
world = concept.get("world")
for target_type in ("broader", "related"):
for target in concept.get(target_type, []):
if not isinstance(target, str):
continue
if target == cid:
errors.append(
f"{rel(CONCEPTS)}: {cid} hat eine {target_type}-Selbstkante"
)
elif target not in concepts:
errors.append(
f"{rel(CONCEPTS)}: {cid}.{target_type} verweist auf "
f"unbekannten Begriff {target}"
)
elif concepts[target].get("world") != world:
errors.append(
f"{rel(CONCEPTS)}: {cid}.{target_type} darf die "
f"Begriffswelt nicht verlassen ({target})"
)
seen_here = set()
labels = [concept.get("preferred", "")] + concept.get("aliases", [])
for label in labels:
if not isinstance(label, str):
continue
normalized = _retrieval_norm(label)
if not normalized:
errors.append(f"{rel(CONCEPTS)}: {cid} enthält einen leeren Suchbegriff")
continue
if normalized in seen_here:
errors.append(
f"{rel(CONCEPTS)}: {cid} enthält den Suchbegriff "
f"{normalized!r} mehrfach"
)
continue
seen_here.add(normalized)
key = (
world if isinstance(world, str) else "<invalid-world>",
normalized,
)
previous = labels_by_world.get(key)
if previous and previous != cid:
errors.append(
f"{rel(CONCEPTS)}: Suchbegriff {normalized!r} kollidiert "
f"in {world} zwischen {previous} und {cid}"
)
else:
labels_by_world[key] = cid
# ``broader`` ist gerichtet und muss azyklisch bleiben. Kahn statt
# rekursiver DFS: auch die maximal erlaubte Registry kann nicht am
# Python-Recursionlimit vorbeilaufen.
outgoing = {cid: [] for cid in concepts}
indegree = {cid: 0 for cid in concepts}
for cid, concept in sorted(concepts.items()):
for target in concept.get("broader", []):
if isinstance(target, str) and target in concepts and target != cid:
outgoing[cid].append(target)
indegree[target] += 1
ready = [cid for cid, degree in indegree.items() if degree == 0]
heapq.heapify(ready)
processed = 0
while ready:
cid = heapq.heappop(ready)
processed += 1
for target in sorted(outgoing[cid]):
indegree[target] -= 1
if indegree[target] == 0:
heapq.heappush(ready, target)
if processed != len(concepts):
cycle_nodes = sorted(
cid for cid, degree in indegree.items() if degree > 0
)
preview = ", ".join(cycle_nodes[:20])
suffix = " …" if len(cycle_nodes) > 20 else ""
errors.append(
f"{rel(CONCEPTS)}: broader-Zyklus in {preview}{suffix}"
)
return worlds, concepts, errors
def parse_register():
"""sources/REGISTER.md-Tabelle lesen.
Spalten: | ID | Titel | Stand/Version | SHA-256 | Trust | Rechte | Ablage |
Rückgabe: (dict sid -> zeile, fehler)
"""
fehler, reg = [], {}
if not _safe_regular_file(REGISTER):
return {}, [f"{rel(REGISTER)}: fehlt oder ist keine reguläre Datei "
f"— Quellenregister ist Pflicht"]
for n, line in enumerate(read(REGISTER).split("\n"), 1):
if not line.strip().startswith("| S-"):
continue
teile = [t.strip() for t in line.strip().strip("|").split("|")]
if len(teile) != 7:
fehler.append(f"{rel(REGISTER)}:{n}: erwartet 7 Spalten, gefunden {len(teile)}")
continue
sid, titel, stand, h, trust, rechte, ablage = teile
if not SID_RE.match(sid):
fehler.append(f"{rel(REGISTER)}:{n}: ungültige Quellen-ID {sid!r}")
continue
if sid in reg:
fehler.append(f"{rel(REGISTER)}:{n}: doppelte Quellen-ID {sid}")
continue
for feldname, wert in (("Titel", titel), ("Stand/Version", stand),
("Trust", trust), ("Rechte", rechte), ("Ablage", ablage)):
if not wert:
fehler.append(f"{rel(REGISTER)}:{n}: Feld {feldname} ist leer")
reg[sid] = {"titel": titel, "stand": stand, "hash": h,
"trust": trust, "rechte": rechte, "ablage": ablage, "zeile": n}
return reg, fehler
def parse_extern_register():
"""sources/EXTERN.md-Tabelle lesen — die Allowlist externer Bezugsquellen.
Spalten: | ID | Titel | Art | Ziel | Stand/Version | Bindungsschlüssel |
| Trust | Rechte |
``Ziel`` ist entweder ein festes https-Präfix oder ``-`` für eine lokale
Quelle. Ein absoluter lokaler Pfad steht hier NIE: er ist eine Eigenschaft
des Hosts und bräche die Portabilität des Artefakts. Die Datei ist die
einzige Stelle, die festlegt, was überhaupt erreichbar ist — es gibt
keinen Codepfad, der ein Ziel aus Anfrage oder Inhalt übernimmt.
"""
fehler, reg = [], {}
if not _safe_regular_file(EXTERN_REGISTER):
# Kein Fehler: ein Tresor ohne externe Bezugsquellen ist der Normalfall.
return {}, []
schluessel = {}
for n, line in enumerate(read(EXTERN_REGISTER).split("\n"), 1):
if not line.strip().startswith("| X-"):
continue
teile = [t.strip() for t in line.strip().strip("|").split("|")]
if len(teile) != 8:
fehler.append(
f"{rel(EXTERN_REGISTER)}:{n}: erwartet 8 Spalten, "
f"gefunden {len(teile)}"
)
continue
xid, titel, art, ziel, stand, key, trust, rechte = teile
if not XID_RE.match(xid):
fehler.append(f"{rel(EXTERN_REGISTER)}:{n}: ungültige Quellen-ID {xid!r}")
continue
if xid in reg:
fehler.append(f"{rel(EXTERN_REGISTER)}:{n}: doppelte Quellen-ID {xid}")
continue
for feldname, wert in (("Titel", titel), ("Art", art), ("Ziel", ziel),
("Stand/Version", stand),
("Bindungsschlüssel", key),
("Trust", trust), ("Rechte", rechte)):
if not wert:
fehler.append(f"{rel(EXTERN_REGISTER)}:{n}: Feld {feldname} ist leer")
if art not in EXTERN_ARTEN:
fehler.append(
f"{rel(EXTERN_REGISTER)}:{n}: Art {art!r} ist keine von "
f"{sorted(EXTERN_ARTEN)}"
)
if trust not in TRUST_WERTE:
fehler.append(
f"{rel(EXTERN_REGISTER)}:{n}: Trust {trust!r} ist keine von "
f"{sorted(TRUST_WERTE)}"
)
if not BINDUNGSSCHLUESSEL_RE.match(key):
fehler.append(
f"{rel(EXTERN_REGISTER)}:{n}: Bindungsschlüssel {key!r} muss "
f"[a-z0-9][a-z0-9-]{{0,63}} sein"
)
elif key in schluessel:
fehler.append(
f"{rel(EXTERN_REGISTER)}:{n}: Bindungsschlüssel {key!r} ist "
f"schon in Zeile {schluessel[key]} vergeben"
)
else:
schluessel[key] = n
url, url_fehler = (None, None) if ziel == "-" else _https_praefix(ziel)
if url_fehler:
fehler.append(f"{rel(EXTERN_REGISTER)}:{n}: Ziel — {url_fehler}")
scope = None
if art == "skillsafe-vault":
gefunden = [wert for wert in EXTERN_SCOPES if wert in stand.lower()]
if len(gefunden) != 1:
fehler.append(
f"{rel(EXTERN_REGISTER)}:{n}: Stand/Version muss bei "
f"skillsafe-vault genau einen Scope aus "
f"{sorted(EXTERN_SCOPES)} nennen"
)
else:
scope = gefunden[0]
reg[xid] = {"titel": titel, "art": art, "ziel": ziel, "url": url,
"stand": stand, "key": key, "trust": trust,
"rechte": rechte, "scope": scope, "zeile": n}
return reg, fehler
def _https_praefix(roh):
"""Ein registriertes Ziel als striktes https-Präfix prüfen.
Rückgabe: ``(praefix, None)`` oder ``(None, grund)``. Bewusst streng:
kein http, kein Benutzer/Passwort im Host, keine Query, kein Fragment.
Ein Präfix ist ein Ort, kein Suchaufruf.
"""
wert = str(roh).strip()
if wert != str(roh):
return None, "führende oder abschließende Leerzeichen sind verboten"
if any(ord(z) < 32 or ord(z) == 127 for z in wert):
return None, "Steuerzeichen sind verboten"
if any(z.isspace() for z in wert):
# Ein Abruf verwirft jede URL mit Leerraum (_unter_praefix); ein
# solches Präfix wäre nie erreichbar.
return None, "Leerraum ist in einem Präfix verboten"
if not wert.startswith("https://"):
return None, "nur https:// ist erlaubt"
rest = wert[len("https://"):]
if not rest or rest.startswith("/"):
return None, "Host fehlt"
if "?" in wert or "#" in wert:
return None, "Query und Fragment sind in einem Präfix verboten"
if "@" in rest.split("/", 1)[0]:
return None, "Zugangsdaten im Host sind verboten"
if ".." in wert:
return None, "'..' ist verboten"
host = rest.split("/", 1)[0].split(":", 1)[0]
if not re.fullmatch(r"[A-Za-z0-9]([A-Za-z0-9.-]*[A-Za-z0-9])?", host):
return None, f"Host {host!r} ist nicht wohlgeformt"
return wert, None
def parse_anchors(extern_register):
"""Satzanker streng validieren — das textuelle Gegenstück zu Medienregionen.
Der ``text`` eines Ankers bleibt untrusted Quelldatum und wird vom
Query-Pfad nie als Evidenz ausgegeben; Evidenz ist immer nur der
kuratierte lokale Claim.
"""
errors, anchors = [], {}
if not _safe_directory(DERIVED):
return {}, []
try:
entries = sorted(DERIVED.iterdir(), key=lambda path: path.name)
except OSError as exc:
return {}, [f"{rel(DERIVED)}: kann nicht gelesen werden — {exc}"]
gesehene_ids = set()
for path in entries:
match = re.fullmatch(r"(X-\d{4})__anchors\.json", path.name)
if not match:
continue
rp = rel(path)
if not _safe_regular_file(path):
errors.append(f"{rp}: nur einfach verlinkte reguläre Dateien erlaubt")
continue
filename_xid = match.group(1)
data = _load_strict_json(path, rp, errors)
if data is None:
continue
required = {"schema", "source_id", "source_kind", "segmentation",
"language", "extractor", "verified", "anchors"}
if not _exact_keys(data, required, set(), rp, errors):
continue
if data.get("schema") != ANCHORS_SCHEMA:
errors.append(f"{rp}.schema: erwartet {ANCHORS_SCHEMA!r}")
if data.get("segmentation") != SEGMENTATION_PROFILE:
errors.append(f"{rp}.segmentation: erwartet {SEGMENTATION_PROFILE!r}")
xid = data.get("source_id")
if not isinstance(xid, str) or not XID_RE.fullmatch(xid):
errors.append(f"{rp}.source_id: erwartet X-nnnn")
continue
if xid != filename_xid:
errors.append(f"{rp}.source_id: {xid!r} passt nicht zu {filename_xid}")
continue
if xid in anchors:
errors.append(f"{rp}: Ankerdatei für {xid} ist doppelt")
continue
if xid not in extern_register:
errors.append(f"{rp}.source_id: Quelle {xid!r} fehlt in {rel(EXTERN_REGISTER)}")
continue
if data.get("source_kind") != extern_register[xid]["art"]:
errors.append(
f"{rp}.source_kind: erwartet "
f"{extern_register[xid]['art']!r} aus {rel(EXTERN_REGISTER)}"
)
language = data.get("language")
if (not isinstance(language, str)
or not re.fullmatch(r"(?:und|[a-z]{2,3}(?:-[A-Za-z0-9]{2,8})*)",
language)):
errors.append(f"{rp}.language: BCP-47-Kurzform oder 'und' erwartet")
extractor = data.get("extractor")
if _exact_keys(extractor, {"kind", "name", "version"}, set(),
f"{rp}.extractor", errors):
if extractor.get("kind") not in EXTRACTOR_KINDS:
errors.append(
f"{rp}.extractor.kind: erwartet einen Wert aus "
f"{sorted(EXTRACTOR_KINDS)}"
)
_plain_text(extractor.get("name"), f"{rp}.extractor.name", errors,
maximum=200)
_plain_text(extractor.get("version"), f"{rp}.extractor.version",
errors, maximum=50)
if data.get("verified") is not True:
errors.append(
f"{rp}.verified: muss vor einem Release true sein — ein "
f"ungeprüfter Anker belegt nichts"
)
liste = data.get("anchors")
if not isinstance(liste, list) or not liste:
errors.append(f"{rp}.anchors: nicht leere Liste erwartet")
continue
eintraege = {}
for pos, anker in enumerate(liste, 1):
label = f"{rp}.anchors[{pos}]"
felder = {"id", "document", "document_sha256", "sentence_index",
"block", "locator", "text", "text_sha256",
"suspicious_instruction"}
if not _exact_keys(anker, felder, set(), label, errors):
continue
aid = anker.get("id")
if not isinstance(aid, str) or not ANCHOR_ID_RE.fullmatch(aid):
errors.append(f"{label}.id: erwartet A-nnnn")
continue
if aid in gesehene_ids:
errors.append(f"{label}.id: {aid} ist tresorweit doppelt")
continue
gesehene_ids.add(aid)
dokument = anker.get("document")
if not isinstance(dokument, str):
errors.append(f"{label}.document: Text erwartet")
continue
# Rein lexikalische Prüfung gegen ROOT: sie wirkt auch dann, wenn
# die Quelle gar nicht gebunden ist, und ist damit unabhängig von
# der Erreichbarkeit der Wurzel.
_, pfadfehler = _safe_relative_path(ROOT, dokument)
if pfadfehler:
errors.append(f"{label}.document: unzulässiger Pfad — {pfadfehler}")
continue
if not dokument.endswith(".md"):
errors.append(f"{label}.document: nur .md-Dokumente sind zitierbar")
for feld in ("document_sha256", "text_sha256"):
wert = anker.get(feld)
if not isinstance(wert, str) or not HASH_RE.fullmatch(wert):
errors.append(f"{label}.{feld}: 64-stelliger SHA-256 erwartet")
index = anker.get("sentence_index")
if not isinstance(index, int) or isinstance(index, bool) or index < 1:
errors.append(f"{label}.sentence_index: positive Ganzzahl erwartet")
if anker.get("block") not in EXTERN_BLOCK_ARTEN:
errors.append(
f"{label}.block: erwartet einen Wert aus "
f"{sorted(EXTERN_BLOCK_ARTEN)}"
)
_plain_text(anker.get("locator"), f"{label}.locator", errors, maximum=200)
_plain_text(anker.get("text"), f"{label}.text", errors, maximum=2000)
if not isinstance(anker.get("suspicious_instruction"), bool):
errors.append(f"{label}.suspicious_instruction: Boolean erwartet")
text = anker.get("text")
if isinstance(text, str):
if _satz_norm(text) != text:
errors.append(
f"{label}.text: muss nach satzsegmentierung/v1 "
f"normalisiert sein (NFC, einfache Leerzeichen)"
)
elif (isinstance(anker.get("text_sha256"), str)
and _satz_digest(text) != anker["text_sha256"]):
errors.append(
f"{label}.text_sha256: passt nicht zum hinterlegten Satz"
)
verdaechtig = bool(PROMPT_INJECTION_RE.search(text))
if isinstance(anker.get("locator"), str):
verdaechtig = verdaechtig or bool(
PROMPT_INJECTION_RE.search(anker["locator"])
)
if verdaechtig and anker.get("suspicious_instruction") is not True:
errors.append(
f"{label}: Instruktionssignatur erkannt — "
f"suspicious_instruction muss true sein"
)
eintraege[aid] = anker
anchors[xid] = {"meta": data, "anchors": eintraege}
return anchors, errors
def parse_orchestrators(extern_register):
"""Katalogdateien externer Markdown-Bäume validieren.
Der Orchestrator ist DATEN, kein zweites Script (AD-09): eine .json, die
dieses Script liest. Er dient als Prefilter, nie als Wahrheit — Stufe 2
des Rankings rechnet immer gegen den tatsächlich gelesenen Text.
"""
errors, kataloge = [], {}
if not _safe_directory(DERIVED):
return {}, []
try:
entries = sorted(DERIVED.iterdir(), key=lambda path: path.name)
except OSError as exc:
return {}, [f"{rel(DERIVED)}: kann nicht gelesen werden — {exc}"]
for path in entries:
match = re.fullmatch(r"(X-\d{4})__orchestrator\.json", path.name)
if not match:
continue
rp = rel(path)
if not _safe_regular_file(path):
errors.append(f"{rp}: nur einfach verlinkte reguläre Dateien erlaubt")
continue
data = _load_strict_json(path, rp, errors)
if data is None:
continue
required = {"schema", "source_id", "segmentation",
"generated_from_sha256", "document_count", "documents"}
if not _exact_keys(data, required, set(), rp, errors):
continue
if data.get("schema") != ORCHESTRATOR_SCHEMA:
errors.append(f"{rp}.schema: erwartet {ORCHESTRATOR_SCHEMA!r}")
if data.get("segmentation") != SEGMENTATION_PROFILE:
errors.append(f"{rp}.segmentation: erwartet {SEGMENTATION_PROFILE!r}")
xid = data.get("source_id")
if not isinstance(xid, str) or not XID_RE.fullmatch(xid):
errors.append(f"{rp}.source_id: erwartet X-nnnn")
continue
if xid != match.group(1):
errors.append(f"{rp}.source_id: {xid!r} passt nicht zu {match.group(1)}")
continue
if xid not in extern_register:
errors.append(f"{rp}.source_id: Quelle {xid!r} fehlt in {rel(EXTERN_REGISTER)}")
continue
if extern_register[xid]["art"] != "markdown-tree":
errors.append(
f"{rp}: ein Katalog ist nur für Art 'markdown-tree' vorgesehen "
f"— ein fremder Tresor bringt seine Claims schon mit"
)
continue
# Ein Katalog behauptet nichts, was er nicht halten kann. Bei einer
# Netzquelle zeigt das Ziel auf einen beweglichen Ref; ein dort
# eingefrorener Hash ist nach dem naechsten fremden Commit unwahr und
# nur noch endlos nachziehbar. Deshalb: bei Netzquellen MUSS er fehlen,
# bei lokalen Quellen MUSS er da sein — der Baum ist dort greifbar.
# Die Regel wirkt in beide Richtungen, sonst ist sie keine.
ist_netzquelle = bool(extern_register[xid].get("url"))
wurzel_hash = data.get("generated_from_sha256")
if ist_netzquelle:
if wurzel_hash is not None:
errors.append(
f"{rp}.generated_from_sha256: muss bei einer Netzquelle "
f"null sein — ein beweglicher Ref laesst sich nicht pinnen"
)
elif not isinstance(wurzel_hash, str) or not HASH_RE.fullmatch(wurzel_hash):
errors.append(f"{rp}.generated_from_sha256: 64-stelliger SHA-256 erwartet")
dokumente = data.get("documents")
if not isinstance(dokumente, list) or not dokumente:
errors.append(f"{rp}.documents: nicht leere Liste erwartet")
continue
if data.get("document_count") != len(dokumente):
# Bewusst redundant: eine abgeschnittene Datei fällt so auf.
errors.append(
f"{rp}.document_count: {data.get('document_count')!r} passt "
f"nicht zu {len(dokumente)} Einträgen"
)
gesehen, eintraege = set(), []
for pos, dok in enumerate(dokumente, 1):
label = f"{rp}.documents[{pos}]"
felder = {"path", "sha256", "title", "summary", "tags",
"sentence_count", "token_count", "top_tokens"}
if not _exact_keys(dok, felder, set(), label, errors):
continue
pfad = dok.get("path")
if not isinstance(pfad, str):
errors.append(f"{label}.path: Text erwartet")
continue
_, pfadfehler = _safe_relative_path(ROOT, pfad)
if pfadfehler:
errors.append(f"{label}.path: unzulässiger Pfad — {pfadfehler}")
continue
if not pfad.endswith(".md"):
errors.append(f"{label}.path: nur .md-Dokumente werden katalogisiert")
if pfad in gesehen:
errors.append(f"{label}.path: {pfad!r} ist doppelt")
continue
gesehen.add(pfad)
dok_hash = dok.get("sha256")
if ist_netzquelle:
if dok_hash is not None:
errors.append(
f"{label}.sha256: muss bei einer Netzquelle null sein"
)
elif not isinstance(dok_hash, str) or not HASH_RE.fullmatch(dok_hash):
errors.append(f"{label}.sha256: 64-stelliger SHA-256 erwartet")
_plain_text(dok.get("title"), f"{label}.title", errors, maximum=300)
_plain_text(dok.get("summary"), f"{label}.summary", errors,
maximum=600, allow_empty=True)
for feld in ("sentence_count", "token_count"):
wert = dok.get(feld)
if not isinstance(wert, int) or isinstance(wert, bool) or wert < 0:
errors.append(f"{label}.{feld}: nicht negative Ganzzahl erwartet")
for feld in ("tags", "top_tokens"):
wert = dok.get(feld)
if not isinstance(wert, list) or not all(
isinstance(t, str) and t for t in wert):
errors.append(f"{label}.{feld}: Liste nicht leerer Texte erwartet")
eintraege.append(dok)
kataloge[xid] = {"meta": data, "documents": eintraege}
return kataloge, errors
def parse_bindung():
"""Maschinenlokale Bindung lesen. Fehlt sie, ist das NIE ein Fehler.
Ungebunden ist der Normalzustand eines frisch entpackten Pakets: der
Tresor antwortet dann vollständig aus seinem eigenen Bestand, und externe
Auflösung meldet fail-closed ``not_bound``. Netzquellen stehen hier nie —
ihre URL ist auf jedem Host dieselbe und schon durch die Registrierung
gebunden.
"""
if not _safe_regular_file(BINDUNG):
return {"bindings": {}, "cache_ttl_seconds": EXTERN_CACHE_TTL}, []
errors = []
rp = rel(BINDUNG)
data = _load_strict_json(BINDUNG, rp, errors)
if data is None:
return {"bindings": {}, "cache_ttl_seconds": EXTERN_CACHE_TTL}, errors
if not _exact_keys(data, {"schema", "bindings"}, {"cache_ttl_seconds"},
rp, errors):
return {"bindings": {}, "cache_ttl_seconds": EXTERN_CACHE_TTL}, errors
if data.get("schema") != BINDING_SCHEMA:
errors.append(f"{rp}.schema: erwartet {BINDING_SCHEMA!r}")
ttl = data.get("cache_ttl_seconds", EXTERN_CACHE_TTL)
if not isinstance(ttl, int) or isinstance(ttl, bool) or ttl < 0:
errors.append(f"{rp}.cache_ttl_seconds: nicht negative Ganzzahl erwartet")
ttl = EXTERN_CACHE_TTL
liste = data.get("bindings")
if not isinstance(liste, list):
errors.append(f"{rp}.bindings: Liste erwartet")
return {"bindings": {}, "cache_ttl_seconds": ttl}, errors
bindings = {}
for pos, eintrag in enumerate(liste, 1):
label = f"{rp}.bindings[{pos}]"
if not _exact_keys(eintrag, {"key", "source_id", "root", "bound_at"},
set(), label, errors):
continue
key, xid = eintrag.get("key"), eintrag.get("source_id")
if not isinstance(key, str) or not BINDUNGSSCHLUESSEL_RE.fullmatch(key):
errors.append(f"{label}.key: [a-z0-9][a-z0-9-]{{0,63}} erwartet")
continue
if not isinstance(xid, str) or not XID_RE.fullmatch(xid):
errors.append(f"{label}.source_id: erwartet X-nnnn")
continue
if not _iso_date(eintrag.get("bound_at")):
errors.append(f"{label}.bound_at: Datum JJJJ-MM-TT erwartet")
if xid in bindings:
errors.append(f"{label}.source_id: {xid} ist doppelt gebunden")
continue
bindings[xid] = {"key": key, "root": eintrag.get("root"),
"bound_at": eintrag.get("bound_at")}
return {"bindings": bindings, "cache_ttl_seconds": ttl}, errors
def parse_media_representations(register):
"""Manifestierbare Bild-/PDF-Repräsentationen streng validieren.
Die Repräsentationen sind nur Fundstellen-Metadaten. Ihr ``text`` wird
niemals direkt vom Query-Pfad als Evidenz ausgegeben.
"""
errors, representations = [], {}
if not _safe_directory(DERIVED):
return {}, [
f"{rel(DERIVED)}: fehlt oder enthält eine unsichere "
f"Symlink-Komponente"
]
try:
entries = sorted(DERIVED.iterdir(), key=lambda path: path.name)
except OSError as exc:
return {}, [f"{rel(DERIVED)}: kann nicht gelesen werden — {exc}"]
for path in entries:
if path.name == "README.md" and _safe_regular_file(path):
continue
rp = rel(path)
if not _safe_regular_file(path):
errors.append(f"{rp}: nur einfach verlinkte reguläre Dateien erlaubt")
continue
if re.fullmatch(r"X-\d{4}__(?:anchors|orchestrator)\.json", path.name):
# Externe Registries haben eigene Parser (parse_anchors,
# parse_orchestrators) und werden hier nur durchgelassen.
continue
match = re.fullmatch(r"(S-\d{4})__media\.json", path.name)
if not match:
errors.append(
f"{rp}: erwartet Dateiname S-nnnn__media.json, "
f"X-nnnn__anchors.json oder X-nnnn__orchestrator.json "
f"(README.md ist die einzige Ausnahme)"
)
continue
filename_sid = match.group(1)
data = _load_strict_json(path, rp, errors)
if data is None:
continue
required = {
"schema", "source_id", "source_sha256", "media_type", "language",
"extractor", "verified", "alt_text", "regions",
}
if not _exact_keys(data, required, set(), rp, errors):
continue
if data.get("schema") != MEDIA_SCHEMA:
errors.append(f"{rp}.schema: erwartet {MEDIA_SCHEMA!r}")
sid = data.get("source_id")
if not isinstance(sid, str) or not SID_RE.fullmatch(sid):
errors.append(f"{rp}.source_id: erwartet S-nnnn")
continue
if sid != filename_sid:
errors.append(
f"{rp}.source_id: {sid!r} passt nicht zu {filename_sid}"
)
continue
if sid in representations:
errors.append(f"{rp}: Repräsentation für {sid} ist doppelt")
continue
if sid not in register:
errors.append(f"{rp}.source_id: Quelle {sid!r} fehlt im REGISTER")
continue
source_hash = data.get("source_sha256")
if source_hash != register[sid].get("hash"):
errors.append(
f"{rp}.source_sha256: stimmt nicht mit REGISTER {sid} überein"
)
source_path, path_error = _safe_relative_path(
ROOT, register[sid].get("ablage", "")
)
if path_error:
errors.append(f"{rp}: Quellenpfad ist unzulässig — {path_error}")
continue
expected_type = MEDIA_TYPES.get(source_path.suffix.lower())
media_type = data.get("media_type")
if expected_type is None:
errors.append(
f"{rp}: {source_path.suffix or '(ohne Endung)'} ist kein "
f"unterstütztes Bild-/PDF-Format"
)
elif media_type != expected_type:
errors.append(
f"{rp}.media_type: erwartet {expected_type!r} für "
f"{source_path.name}"
)
elif source_path.is_file() and not _media_signature_matches(
source_path, expected_type):
errors.append(
f"{rp}: Dateisignatur von {source_path.name} passt nicht zu "
f"{expected_type}"
)
language = data.get("language")
if (not isinstance(language, str)
or not re.fullmatch(r"(?:und|[a-z]{2,3}(?:-[A-Za-z0-9]{2,8})*)",
language)):
errors.append(f"{rp}.language: BCP-47-Kurzform oder 'und' erwartet")
_plain_text(data.get("alt_text"), f"{rp}.alt_text", errors, maximum=1000)
if (isinstance(data.get("alt_text"), str)
and PROMPT_INJECTION_RE.search(data["alt_text"])):
errors.append(
f"{rp}.alt_text: offensichtliche Instruktionssignatur ist "
f"als Alttext verboten"
)
extractor = data.get("extractor")
if _exact_keys(
extractor, {"kind", "name", "version"}, set(),
f"{rp}.extractor", errors):
if (not isinstance(extractor.get("kind"), str)
or extractor.get("kind") not in EXTRACTOR_KINDS):
errors.append(
f"{rp}.extractor.kind: erwartet "
f"{sorted(EXTRACTOR_KINDS)}"
)
_plain_text(
extractor.get("name"), f"{rp}.extractor.name", errors, maximum=120
)
_plain_text(
extractor.get("version"), f"{rp}.extractor.version",
errors, maximum=80
)
if data.get("verified") is not True:
errors.append(
f"{rp}.verified: muss nach Sicht-/Qualitätsprüfung true sein"
)
regions_raw = data.get("regions")
if not isinstance(regions_raw, list) or not regions_raw:
errors.append(f"{rp}.regions: nicht leere Liste erwartet")
regions_raw = []
if len(regions_raw) > 1000:
errors.append(f"{rp}.regions: höchstens 1000 Regionen")
regions = {}
region_required = {
"id", "kind", "locator", "text", "confidence", "bbox",
"suspicious_instruction",
}
for index, region in enumerate(regions_raw, 1):
field = f"{rp}.regions[{index}]"
if not _exact_keys(region, region_required, set(), field, errors):
continue
rid = region.get("id")
if not isinstance(rid, str) or not REGION_ID_RE.fullmatch(rid):
errors.append(f"{field}.id: erwartet R-nnnn")
continue
if rid in regions:
errors.append(f"{field}.id: Region {rid} ist doppelt")
continue
if (not isinstance(region.get("kind"), str)
or region.get("kind") not in REGION_KINDS):
errors.append(f"{field}.kind: erwartet {sorted(REGION_KINDS)}")
_plain_text(
region.get("locator"), f"{field}.locator", errors, maximum=500
)
_plain_text(
region.get("text"), f"{field}.text", errors, maximum=20000
)
confidence = region.get("confidence")
if (isinstance(confidence, bool)
or not isinstance(confidence, (int, float))
or not 0 <= confidence <= 1):
errors.append(f"{field}.confidence: Zahl zwischen 0 und 1 erwartet")
suspicious = region.get("suspicious_instruction")
if not isinstance(suspicious, bool):
errors.append(f"{field}.suspicious_instruction: Boolean erwartet")
elif (
any(
isinstance(region.get(key), str)
and PROMPT_INJECTION_RE.search(region[key])
for key in ("text", "locator")
)
and suspicious is not True):
errors.append(
f"{field}: offensichtliche Instruktionssignatur muss "
f"als suspicious_instruction=true markiert sein"
)
bbox = region.get("bbox")
if bbox is not None:
valid_bbox = (
isinstance(bbox, list) and len(bbox) == 4
and all(
not isinstance(value, bool)
and isinstance(value, (int, float))
for value in bbox
)
)
if valid_bbox:
x, y, width, height = bbox
valid_bbox = (
0 <= x <= 1 and 0 <= y <= 1
and 0 < width <= 1 and 0 < height <= 1
and x + width <= 1.000000001
and y + height <= 1.000000001
)
if not valid_bbox:
errors.append(
f"{field}.bbox: null oder normalisierte "
f"[x,y,breite,höhe] innerhalb 0..1 erwartet"
)
regions[rid] = region
representations[sid] = {
"path": rp,
"source_id": sid,
"source_sha256": source_hash,
"media_type": media_type,
"language": language,
"alt_text": data.get("alt_text"),
"regions": regions,
}
for sid, entry in sorted(register.items()):
source_path, path_error = _safe_relative_path(ROOT, entry.get("ablage", ""))
if path_error:
continue
suffix = source_path.suffix.lower()
if suffix in ACTIVE_MEDIA_SUFFIXES:
errors.append(
f"REGISTER {sid}: aktive Bildformate wie SVG sind nicht erlaubt; "
f"lokal in PNG/JPEG rasterisieren und neu registrieren"
)
elif suffix in MEDIA_TYPES and sid not in representations:
errors.append(
f"REGISTER {sid}: Bild-/PDF-Quelle braucht "
f"sources/derived/{sid}__media.json"
)
return representations, errors
def parse_router():
"""ROUTER.md lesen. Rückgabe: (dict domain -> {schlagworte, seiten}, fehler)"""
fehler, router, dom = [], {}, None
if not _safe_regular_file(ROUTER):
return {}, [f"{rel(ROUTER)}: fehlt oder ist keine reguläre Datei "
f"— Schlagwort-Router ist Pflicht"]
for n, line in enumerate(read(ROUTER).split("\n"), 1):
s = line.strip()
if s.startswith("## "):
dom = s[3:].strip()
if dom in router:
fehler.append(f"{rel(ROUTER)}:{n}: Domäne {dom!r} ist doppelt definiert")
dom = None
continue
router[dom] = {"schlagworte": [], "seiten": [], "zeile": n}
elif dom and s.startswith("schlagworte:"):
router[dom]["schlagworte"] = [
w.strip().lower() for w in s.split(":", 1)[1].split(",") if w.strip()]
elif dom and s.startswith("- knowledge/"):
router[dom]["seiten"].append(s[2:].strip())
return router, fehler
# ---------------------------------------------------------------- Seiten
def lade_seiten(register, typen, reltypen, concepts=None, media=None,
extern=None, anchors=None):
"""Alle Wissensseiten laden und prüfen. Rückgabe: (seiten, claims, fehler, warnungen)."""
concepts = concepts or {}
media = media or {}
extern = extern or {}
anchors = anchors or {}
fehler, warnungen, seiten, alle_claims = [], [], {}, {}
for p in iter_pages():
rp = rel(p)
if not _resolved_within(p, KNOWLEDGE):
fehler.append(f"{rp}: Datei oder Symlink zeigt aus knowledge/ hinaus")
continue
seitentext = read(p)
fm, body, fm_fehler, offset = parse_frontmatter(seitentext, rp)
fehler.extend(fm_fehler)
unbekannt = sorted(
set(fm) - set(REQUIRED_FIELDS) - OPTIONAL_FIELDS
)
if unbekannt:
fehler.append(f"{rp}: unbekannte Frontmatter-Felder {unbekannt}")
for feld in REQUIRED_FIELDS:
if feld not in fm or fm[feld] in ("", []):
# 'sources' darf genau dann leer sein, wenn die Seite
# ausschließlich aus aufgeführten externen Bezugsquellen
# belegt ist. Ganz ohne Beleg bleibt sie unzulässig.
if feld == "sources" and fm.get("externe_quellen"):
continue
fehler.append(f"{rp}: Pflichtfeld {feld!r} fehlt oder ist leer")
for feld in LIST_FIELDS:
if feld in fm and not isinstance(fm[feld], list):
fehler.append(f"{rp}: Frontmatter-Feld {feld!r} muss eine Liste sein")
for feld in (set(REQUIRED_FIELDS) - LIST_FIELDS) | OPTIONAL_SCALAR_FIELDS:
if feld in fm and not isinstance(fm[feld], str):
fehler.append(f"{rp}: Frontmatter-Feld {feld!r} muss Text sein")
# Eine Seite, die das Manifest nicht erfasst, wäre Wissen ohne
# Integritätsschutz: ihr Wortlaut könnte sich nach dem Release ändern,
# ohne dass Sperre oder Siegel es bemerken.
if not _tracked_path(p):
fehler.append(
f"{rp}: liegt in einem Pfad, den das Manifest ausnimmt "
f"(__pycache__); dort darf keine Wissensseite stehen")
typ = fm.get("type", "")
if typ and typ not in typen:
fehler.append(f"{rp}: Typ {typ!r} nicht in schema/types.yaml — "
f"Type-Onboarding durchführen, bevor eingelesen wird (fail-closed)")
if p.name.lower() in RESERVIERTE_DATEINAMEN:
fehler.append(
f"{rp}: {p.name} ist ein reservierter Dateiname (OKF v0.2 §3.1) "
f"und darf keine Wissensseite sein; beim Export würde der "
f"generierte Index sie überschreiben")
if p.parent.parent != KNOWLEDGE:
fehler.append(f"{rp}: Seiten liegen genau eine Ebene tief: knowledge/<domäne>/<seite>.md")
elif fm.get("domain") != p.parent.name:
fehler.append(f"{rp}: domain={fm.get('domain')!r} ≠ Ordner {p.parent.name!r} "
f"(Quellentrennung ist baulich)")
if fm.get("status") not in STATUS_WERTE:
fehler.append(f"{rp}: status muss eins sein von {sorted(STATUS_WERTE)}")
if fm.get("confidence") not in CONF_WERTE:
fehler.append(f"{rp}: confidence muss eins sein von {sorted(CONF_WERTE)}")
stand = _iso_date(fm.get("stand", ""))
if stand is None:
fehler.append(f"{rp}: stand muss ein gültiges Datum JJJJ-MM-TT sein")
if not VERSION_RE.match(str(fm.get("version", ""))):
fehler.append(f"{rp}: version muss SemVer sein (z. B. 1.0.0)")
# Optionale Prüfangabe (OKF v0.2 §5.2/§5.3, hier flach und deutsch).
# Sie tritt als Paar auf oder gar nicht: ein Prüfer ohne Datum ist
# nicht nachvollziehbar, ein Datum ohne Prüfer nicht zurechenbar.
geprueft_von = fm.get("geprueft_von")
geprueft_am = fm.get("geprueft_am")
if isinstance(geprueft_von, str) or isinstance(geprueft_am, str):
if not (isinstance(geprueft_von, str) and isinstance(geprueft_am, str)):
fehler.append(
f"{rp}: geprueft_von und geprueft_am treten nur gemeinsam "
f"auf; eine Prüfung braucht Prüfer und Datum")
if isinstance(geprueft_von, str):
if _plain_text(geprueft_von, f"{rp}: geprueft_von", fehler, maximum=128):
if PROMPT_INJECTION_RE.search(geprueft_von):
fehler.append(
f"{rp}: geprueft_von enthält eine offensichtliche "
f"Instruktionssignatur")
elif not ACTOR_RE.match(geprueft_von):
fehler.append(
f"{rp}: geprueft_von muss 'mensch:<id>', "
f"'prozess:<id>' oder 'agent:<name>/<version>' sein, "
f"nicht {geprueft_von!r}")
if isinstance(geprueft_am, str):
geprueft_datum = _iso_date(geprueft_am)
if geprueft_datum is None:
fehler.append(
f"{rp}: geprueft_am muss ein gültiges Datum JJJJ-MM-TT sein")
elif stand is not None and geprueft_datum < stand:
# Kein Fehler: eine Prüfung DARF älter als die letzte
# inhaltliche Änderung sein. Sie ist dann nur nicht mehr
# aussagekräftig, und genau das soll sichtbar werden.
warnungen.append(
f"{rp}: geprueft_am {geprueft_am} liegt vor stand "
f"{fm.get('stand')} — die Prüfung deckt den aktuellen "
f"Inhalt nicht mehr")
quellen = fm.get("sources", [])
if not isinstance(quellen, list):
quellen = []
for sid in quellen:
if not isinstance(sid, str) or not SID_RE.fullmatch(sid):
fehler.append(f"{rp}: ungültige Quellen-ID {sid!r}")
elif sid not in register:
fehler.append(f"{rp}: Quelle {sid} steht nicht im Register")
# Externe Bezugsquellen stehen in einem eigenen Feld, nicht in
# 'sources:'. Grund: 'sources' bildet beim OKF-Export auf §5.1 ab und
# wird an mehreren Stellen als Registerschlüssel gelesen. Ein Feld
# additiv hinzuzufügen ist rückwärtskompatibel, die Bedeutung eines
# bestehenden zu ändern ist es nicht.
externe = fm.get("externe_quellen", [])
if not isinstance(externe, list):
externe = []
if len(externe) != len(set(x for x in externe if isinstance(x, str))):
fehler.append(f"{rp}: doppelte IDs in externe_quellen")
for xid in externe:
if not isinstance(xid, str) or not XID_RE.fullmatch(xid):
fehler.append(f"{rp}: ungültige externe Quellen-ID {xid!r}")
elif xid not in extern:
fehler.append(
f"{rp}: externe Quelle {xid} steht nicht in "
f"{rel(EXTERN_REGISTER)}"
)
# Freitext der Seite: die Kommentarzeilen des Frontmatters, die der
# Parser überspringt, und der Rumpf außerhalb der Claims (Kurzfassung,
# Kontext, Grenzen). Die Engine gibt beides nicht aus, der
# Antworten-Workflow liest die Seite aber ganz. Geprüft wird je
# Absatz, damit ein Zeilenumbruch eine Signatur nicht teilt
# (_freitext_laeufe), die lange Formel je Abschnitt
# (_freitext_abschnitte).
datei_zeilen, rumpf_zeilen = seitentext.split("\n"), body.split("\n")
freitext_treffer = sorted(
set(_freitext_signaturen(_freitext_laeufe(
datei_zeilen, offset, rumpf_zeilen)))
| set(_freitext_signaturen(_freitext_abschnitte(
datei_zeilen, offset, rumpf_zeilen), IGNORE_SIGNATUR_RE)))
if _pfad_mit_signatur(rp):
teile = rp.split("/")
ort = ("knowledge/" + teile[1] if len(teile) > 2
and not _pfad_mit_signatur(teile[1]) else "knowledge")
warnungen.append(
f"{ort}: Der Pfad einer Seite enthält eine offensichtliche "
f"Instruktionssignatur — query und sweep markieren die Seite")
for nummer in freitext_treffer:
if nummer <= offset:
warnungen.append(
f"{rp}:{nummer}: Instruktionssignatur in einer "
f"Kommentarzeile des Frontmatters — das Modell liest "
f"sie mit der Seite")
else:
warnungen.append(
f"{rp}:{nummer}: Instruktionssignatur im Text der Seite "
f"außerhalb der Claims — das Modell liest ihn mit")
if _hat_signatur(fm.get("title")):
warnungen.append(
f"{rp}: Titel enthält eine offensichtliche "
f"Instruktionssignatur — query und sweep geben ihn nicht aus")
tags = fm.get("tags", [])
if isinstance(tags, list):
for nummer, tag in enumerate(tags, 1):
if not isinstance(tag, str) or not _retrieval_norm(tag):
fehler.append(f"{rp}: ungültiger oder leerer Tag {tag!r}")
continue
if any(zeichen in tag for zeichen in ",[]"):
fehler.append(
f"{rp}: Tag Nr. {nummer} enthält ',' '[' oder ']'; "
f"in der Inline-Listenform ist das nicht darstellbar "
f"und zerlegt den Wert")
if _hat_signatur(tag):
# Ohne Wortlaut: query und sweep geben die Warnungen mit
# aus, und dort darf die Signatur nicht stehen.
warnungen.append(
f"{rp}: Tag Nr. {nummer} enthält eine offensichtliche "
f"Instruktionssignatur — query und sweep geben ihn "
f"nicht aus")
concept_ids = fm.get("concepts", [])
if not isinstance(concept_ids, list):
concept_ids = []
if len(concept_ids) != len(set(
item for item in concept_ids if isinstance(item, str))):
fehler.append(f"{rp}: doppelte IDs in concepts")
for concept_id in concept_ids:
if (not isinstance(concept_id, str)
or not CONCEPT_ID_RE.fullmatch(concept_id)):
fehler.append(f"{rp}: concepts enthält ungültige ID {concept_id!r}")
elif concept_id not in concepts:
fehler.append(f"{rp}: Begriff {concept_id} fehlt in schema/begriffswelten.json")
# Claims (Grammatik siehe schema/profil.md)
claims = []
for bn, line in enumerate(rumpf_zeilen, 1):
n = offset + bn
if not line.startswith(CLAIM_START):
# Freitext; den prüft der Stolperdraht oben.
continue
m = CLAIM_RE.match(line)
if not m:
fehler.append(f"{rp}:{n}: Claim-Zeile verletzt die Grammatik "
f"'- **C-nnnn** [S-nnnn|X-nnnn | Fundstelle | "
f"Wortlaut|Beobachtung|Auslegung] Text'")
continue
cid, sid, fundstelle, art, text = m.groups()
fundstelle = fundstelle.strip()
text = text.strip()
_plain_text(
fundstelle, f"{rp}:{n}: {cid} Fundstelle", fehler, maximum=1000
)
_plain_text(
text, f"{rp}:{n}: {cid} Aussagetext", fehler, maximum=20000
)
for feld, wert in (("Fundstelle", fundstelle), ("Aussagetext", text)):
if PROMPT_INJECTION_RE.search(wert):
fehler.append(
f"{rp}:{n}: {cid} {feld} enthält eine offensichtliche "
"Instruktionssignatur und darf nicht als Claim "
"freigegeben werden"
)
if cid in alle_claims:
fehler.append(f"{rp}:{n}: Claim-ID {cid} bereits vergeben "
f"in {alle_claims[cid]['seite']}")
ist_extern = sid.startswith("X-")
if ist_extern:
if sid not in extern:
fehler.append(
f"{rp}:{n}: {cid} verweist auf nicht aufgeführte "
f"externe Quelle {sid}"
)
elif sid not in externe:
fehler.append(
f"{rp}:{n}: {cid} nutzt {sid}, aber {sid} fehlt in "
f"'externe_quellen:' des Frontmatters"
)
elif sid not in register:
fehler.append(f"{rp}:{n}: {cid} verweist auf unregistrierte Quelle {sid}")
elif sid not in quellen:
fehler.append(f"{rp}:{n}: {cid} nutzt {sid}, aber {sid} fehlt in "
f"'sources:' des Frontmatters")
# Satzanker sind das textuelle Gegenstück zu Medienregionen: bei
# einer externen Quelle enthält die Fundstelle genau eine
# existierende A-nnnn, und ein als verdächtig markierter Anker
# darf nie einen Claim tragen.
anchor_id = None
anchor_ids = re.findall(r"(?<![A-Za-z0-9])A-\d{4}(?![A-Za-z0-9])",
fundstelle)
if ist_extern:
if len(anchor_ids) != 1:
fehler.append(
f"{rp}:{n}: {cid} auf externe Quelle {sid} braucht "
f"genau einen Satzanker A-nnnn in der Fundstelle"
)
else:
anchor_id = anchor_ids[0]
anker = anchors.get(sid, {}).get("anchors", {}).get(anchor_id)
if anker is None:
fehler.append(
f"{rp}:{n}: {cid} verweist auf unbekannten Anker "
f"{anchor_id} in {sid}"
)
elif anker.get("suspicious_instruction") is True:
fehler.append(
f"{rp}:{n}: {cid} darf verdächtigen Anker "
f"{anchor_id} nicht als Evidenz nutzen"
)
elif anchor_ids:
fehler.append(
f"{rp}:{n}: {cid} nennt einen Satzanker, aber {sid} ist "
f"keine aufgeführte externe Bezugsquelle"
)
region_id = None
region_ids = re.findall(r"(?<![A-Za-z0-9])R-\d{4}(?![A-Za-z0-9])",
fundstelle)
if sid in media:
if len(region_ids) != 1:
fehler.append(
f"{rp}:{n}: {cid} auf Bild/PDF {sid} braucht genau "
f"eine Region R-nnnn in der Fundstelle"
)
else:
region_id = region_ids[0]
region = media[sid]["regions"].get(region_id)
if region is None:
fehler.append(
f"{rp}:{n}: {cid} verweist auf unbekannte Region "
f"{region_id} in {sid}"
)
elif region.get("suspicious_instruction") is True:
fehler.append(
f"{rp}:{n}: {cid} darf verdächtige Region "
f"{region_id} nicht als Evidenz nutzen"
)
elif region_ids:
fehler.append(
f"{rp}:{n}: {cid} nennt eine Region, aber {sid} ist "
f"keine registrierte Bild-/PDF-Repräsentation"
)
if art == "Beobachtung" and sid not in media:
fehler.append(
f"{rp}:{n}: {cid} nutzt Beobachtung ohne Bild-/PDF-Quelle"
)
eintrag = {"id": cid, "quelle": sid, "fundstelle": fundstelle,
"art": art, "text": text, "seite": rp,
"region": region_id, "anker": anchor_id,
"extern": ist_extern}
claims.append(eintrag)
alle_claims[cid] = eintrag
if not claims:
warnungen.append(f"{rp}: keine Claims — Kurzfassung wäre unbelegt")
# Relationen (typisierte Kanten; dürfen Domänen überschreiten)
relationen = []
rels = fm.get("relations", [])
if not isinstance(rels, list):
rels = []
for r in rels:
m = REL_RE.match(r)
if not m:
fehler.append(f"{rp}: relation {r!r} verletzt das Format 'typ -> domäne/seite.md'")
continue
rtyp, ziel = m.group(1), m.group(2).strip()
if rtyp not in reltypen:
fehler.append(f"{rp}: Relationstyp {rtyp!r} nicht in _relationstypen "
f"(types.yaml) — erst dort deklarieren")
ziel_rel = Path(ziel)
if len(ziel_rel.parts) != 2 or ziel_rel.suffix != ".md":
fehler.append(f"{rp}: Relationsziel {ziel!r} muss "
f"'domäne/seite.md' entsprechen")
continue
zielpfad, pfadfehler = _safe_relative_path(KNOWLEDGE, ziel)
if pfadfehler:
fehler.append(f"{rp}: Relationsziel {ziel!r} unzulässig — {pfadfehler}")
continue
if not zielpfad.is_file():
fehler.append(f"{rp}: Relationsziel knowledge/{ziel} existiert nicht")
continue
relationen.append({"typ": rtyp, "ziel": "knowledge/" + ziel})
# Links im Fließtext: Inline- und Referenzziele werden geprüft;
# HTML-Links bleiben außerhalb der bewusst kleinen Markdown-Untermenge.
if HTML_LINK_RE.search(body):
fehler.append(f"{rp}: HTML-Links/-Bilder sind nicht unterstützt — "
f"portable Markdown-Linksyntax verwenden")
link_kandidaten = [m.group(1) for m in LINK_RE.finditer(body)]
link_kandidaten += [m.group(1) for m in REFERENCE_LINK_RE.finditer(body)]
for link_raw in link_kandidaten:
ziel, linkfehler = _markdown_link_target(link_raw)
if linkfehler:
fehler.append(f"{rp}: Markdown-Link unzulässig — {linkfehler}")
continue
if ziel.startswith(("http://", "https://", "mailto:", "#")):
continue
dateiziel = ziel.split("#", 1)[0]
aufgeloest, pfadfehler = _safe_relative_path(p.parent, dateiziel)
if pfadfehler:
fehler.append(f"{rp}: Markdown-Link {ziel!r} unzulässig — {pfadfehler}")
continue
if aufgeloest.is_symlink():
fehler.append(f"{rp}: Markdown-Link {ziel!r} zeigt auf einen Symlink")
continue
if not aufgeloest.is_file():
fehler.append(f"{rp}: toter Link {ziel!r}")
continue
seiten[rp] = {
"fm": fm, "claims": claims, "relationen": relationen, "pfad": p,
"zeilen": len(rumpf_zeilen), "body": body,
"freitext_signatur": bool(freitext_treffer),
}
for rp, seite in sorted(seiten.items()):
for relation in seite["relationen"]:
if relation["ziel"] not in seiten:
fehler.append(f"{rp}: Relationsziel {relation['ziel']} ist keine "
f"validierte Wissensseite")
return seiten, alle_claims, fehler, warnungen
# ------------------------------------------------------------- Kommandos
def cmd_validate(still=False):
typen, reltypen, fehler = parse_types()
register, f2 = parse_register()
fehler += f2
_, concepts, concept_errors = parse_concepts()
fehler += concept_errors
media, media_errors = parse_media_representations(register)
fehler += media_errors
extern, extern_errors = parse_extern_register()
fehler += extern_errors
anchors, anchor_errors = parse_anchors(extern)
fehler += anchor_errors
orchestrators, orchestrator_errors = parse_orchestrators(extern)
fehler += orchestrator_errors
try:
for p in _skill_symlinks():
fehler.append(f"{rel(p)}: Symlink im Tresor verboten — "
f"portable Releases enthalten nur echte Dateien/Ordner")
for p in _skill_hardlinks():
fehler.append(f"{rel(p)}: mehrfach hart verlinkte Datei im Tresor verboten "
f"— Inhalt könnte außerhalb der Ordnergrenze verändert werden")
for p, grund in _skill_fremdartefakte():
fehler.append(f"{rel(p)}: {grund} — der Tresor liefert Wissen aus, "
f"keinen ausführbaren Inhalt")
for p, zeile, form in _skill_geheimnisse():
fehler.append(f"{rel(p)}:{zeile}: mögliches Geheimnis ({form}) — "
f"Zugangsdaten gehören nicht in ein portables Artefakt; "
f"Quelle schwärzen und neu registrieren")
except OSError as exc:
fehler.append(f"Tresorbaum kann nicht vollständig geprüft werden — {exc}")
for p in _quarantine_payloads():
fehler.append(f"{rel(p)}: Quarantäne fehlt, ist unsicher oder nicht leer — "
f"ungeprüfte Inhalte vor Validierung freigeben oder entfernen")
# Registerzeilen materiell prüfen: Ablage existiert, ist eindeutig und Hash stimmt
registrierte_ablagen = {}
for sid, r in sorted(register.items()):
if r["trust"] not in TRUST_WERTE:
fehler.append(f"REGISTER {sid}: Trust muss T1/T2/T3 sein")
if r["rechte"].strip().upper() in {
"", "-", "?", "N/A", "NA", "RECHTE", "TODO", "TBD",
"OFFEN", "UNKLAR", "UNGEKLÄRT", "UNKNOWN"}:
fehler.append(f"REGISTER {sid}: Rechte müssen vor Ingest eindeutig geklärt sein")
if not HASH_RE.match(r["hash"]):
fehler.append(f"REGISTER {sid}: SHA-256 hat kein gültiges Format")
ablage, pfadfehler = _safe_relative_path(ROOT, r["ablage"])
if pfadfehler:
fehler.append(f"REGISTER {sid}: Ablage {r['ablage']!r} unzulässig — "
f"{pfadfehler}")
continue
if ablage.parent != RAW or not ablage.name.startswith(f"{sid}__"):
fehler.append(f"REGISTER {sid}: Ablage muss direkt unter sources/raw/ liegen "
f"und mit '{sid}__' beginnen")
continue
if ablage.is_symlink():
fehler.append(f"REGISTER {sid}: Ablage darf kein Symlink sein")
continue
if ablage in registrierte_ablagen:
fehler.append(f"REGISTER {sid}: Ablage wird bereits von "
f"{registrierte_ablagen[ablage]} verwendet")
continue
registrierte_ablagen[ablage] = sid
if not ablage.is_file():
fehler.append(f"REGISTER {sid}: Ablage {r['ablage']} existiert nicht")
else:
if HASH_RE.match(r["hash"]) and sha256_file(ablage) != r["hash"]:
fehler.append(f"REGISTER {sid}: Hash der Ablage weicht vom Register ab "
f"— Quelle wurde nach Registrierung verändert")
expected_media = MEDIA_TYPES.get(ablage.suffix.lower())
detected_media = _detected_media_type(ablage)
if detected_media and expected_media != detected_media:
fehler.append(
f"REGISTER {sid}: Dateisignatur ist {detected_media}, aber "
f"Endung {ablage.suffix or '(keine)'} ist dafür nicht erlaubt "
f"— Quelle nicht als Text tarnen"
)
elif expected_media and detected_media != expected_media:
fehler.append(
f"REGISTER {sid}: Endung {ablage.suffix} erwartet "
f"{expected_media}, Dateisignatur passt nicht"
)
if _safe_directory(RAW):
try:
raw_baum = _walk_tree_no_links(RAW)
raw_eintraege = sorted(
(p for p in raw_baum if _safe_regular_file(p) or _is_path_alias(p)),
key=lambda p: rel(p),
)
for p in raw_eintraege:
if p not in registrierte_ablagen:
fehler.append(f"{rel(p)}: Rohquelle ist nicht eindeutig im REGISTER erfasst")
for p in sorted(
(p for p in raw_baum if _safe_directory(p)),
key=lambda p: rel(p)):
if p != RAW:
fehler.append(f"{rel(p)}: Unterordner in sources/raw/ sind nicht erlaubt")
except OSError as exc:
fehler.append(f"sources/raw: Baum kann nicht vollständig geprüft werden — {exc}")
else:
fehler.append("sources/raw: fehlt oder enthält eine unsichere Symlink-Komponente")
if _safe_directory(KNOWLEDGE):
try:
for p in _walk_tree_no_links(KNOWLEDGE):
if (_safe_regular_file(p) or _is_path_alias(p)) and p.suffix != ".md":
fehler.append(f"{rel(p)}: knowledge/ enthält nur validierte Markdown-Seiten")
except OSError as exc:
fehler.append(f"knowledge: Baum kann nicht vollständig geprüft werden — {exc}")
else:
fehler.append("knowledge: fehlt oder enthält eine unsichere Symlink-Komponente")
try:
seiten, claims, f3, warnungen = lade_seiten(
register, typen, reltypen, concepts=concepts, media=media,
extern=extern, anchors=anchors
)
fehler += f3
except (OSError, UnicodeError) as exc:
seiten, claims, warnungen = {}, {}, []
fehler.append(f"knowledge: Seiten können nicht vollständig gelesen werden — {exc}")
# Titel, Stand und Rechte einer Quelle gibt query an jedem Beleg aus. Eine
# Instruktionssignatur dort ist eine Warnung; ausgegeben wird das Feld dann
# nicht (_ohne_signatur).
for name, reg in ((rel(REGISTER), register), (rel(EXTERN_REGISTER), extern)):
for kennung, zeile in sorted(reg.items()):
for feld, schluessel in (("Titel", "titel"),
("Stand/Version", "stand"),
("Rechte", "rechte"),
("Ziel", "ziel")):
if _hat_signatur(zeile.get(schluessel)):
warnungen.append(
f"{name}: {kennung} {feld} enthält eine offensichtliche "
f"Instruktionssignatur — query gibt das Feld nicht aus")
# Dokumentpfade aus einem Katalog oder einer Ankerdatei nennt query
# --extern als Kennung eines Treffers; eine Signatur darin ist eine
# Warnung, und der Treffer trägt das Signal suspicious_instruction.
for kennung, katalog in sorted(orchestrators.items()):
for nummer, dok in enumerate(katalog["documents"], 1):
if _pfad_mit_signatur(dok.get("path")):
warnungen.append(
f"Katalog {kennung}: Dokument Nr. {nummer} hat einen Pfad "
f"mit offensichtlicher Instruktionssignatur — query --extern "
f"markiert seine Treffer")
for kennung, eintrag in sorted(anchors.items()):
for aid, anker in sorted(eintrag["anchors"].items()):
if _pfad_mit_signatur(anker.get("document")):
warnungen.append(
f"Anker {aid} ({kennung}): Dokumentpfad mit offensichtlicher "
f"Instruktionssignatur")
for concept_id, concept in sorted(concepts.items()):
claim_id = concept.get("definition_claim")
if not isinstance(claim_id, str) or claim_id not in claims:
fehler.append(
f"{rel(CONCEPTS)}: {concept_id}.definition_claim {claim_id!r} "
f"existiert nicht"
)
continue
page = seiten.get(claims[claim_id]["seite"])
page_concepts = page["fm"].get("concepts", []) if page else []
if concept_id not in page_concepts:
fehler.append(
f"{rel(CONCEPTS)}: Definition {claim_id} liegt auf einer Seite, "
f"die {concept_id} nicht in concepts führt"
)
referenced_media = {
claim["quelle"] for claim in claims.values() if claim.get("region")
}
for sid in sorted(set(media) - referenced_media):
warnungen.append(
f"{media[sid]['path']}: freigegebene Medienrepräsentation ohne Claim"
)
# Jede aufgeführte externe Quelle braucht ihre Ankerdatei; verwaiste Anker
# sind eine Warnung, kein Fehler — sie belegen nur nichts (mehr).
referenced_anchors = {
(claim["quelle"], claim["anker"]) for claim in claims.values()
if claim.get("anker")
}
for xid in sorted(extern):
# Kein Fehler: eine Quelle darf aufgeführt sein, ohne dass schon ein
# Claim sie zitiert — sie steht dann für das Nachschlagen bereit, und
# ihr Katalog belegt das. Erst eine Quelle ohne Anker UND ohne Katalog
# ist für gar nichts aufgeführt. Ein Claim ohne existierenden Anker
# fällt im Claim-Zweig von lade_seiten auf, nicht hier.
if xid not in anchors and xid not in orchestrators:
warnungen.append(
f"{rel(EXTERN_REGISTER)}: {xid} ist aufgeführt, aber weder "
f"satzweise belegt noch katalogisiert — die Quelle trägt nichts"
)
for xid in sorted(anchors):
for aid in sorted(anchors[xid]["anchors"]):
if (xid, aid) not in referenced_anchors:
warnungen.append(
f"sources/derived/{xid}__anchors.json: Anker {aid} wird "
f"von keinem Claim genutzt"
)
# Router: jede Domäne hat Abschnitt, jede gelistete Seite existiert und passt
router, f4 = parse_router()
fehler += f4
try:
domaenen = (
sorted({d.name for d in KNOWLEDGE.iterdir()
if _safe_directory(d) and d.parent == KNOWLEDGE})
if _safe_directory(KNOWLEDGE) else []
)
except OSError as exc:
domaenen = []
fehler.append(f"knowledge: Domänen können nicht aufgelistet werden — {exc}")
for d in domaenen:
if d not in router:
fehler.append(f"ROUTER.md: Domäne {d!r} hat keinen Abschnitt — jede Domäne "
f"braucht Schlagworte und Seitenliste")
for d, sec in sorted(router.items()):
if d not in domaenen:
fehler.append(f"ROUTER.md: Abschnitt {d!r} ohne Domänen-Ordner knowledge/{d}/")
if not sec["schlagworte"]:
fehler.append(f"ROUTER.md [{d}]: keine Schlagworte")
for s in sec["seiten"]:
seitenpfad, pfadfehler = _safe_relative_path(ROOT, s)
if pfadfehler or not _resolved_within(seitenpfad, KNOWLEDGE):
grund = pfadfehler or "Pfad zeigt aus knowledge/ hinaus"
fehler.append(f"ROUTER.md [{d}]: Seite {s!r} unzulässig — {grund}")
elif not seitenpfad.is_file():
fehler.append(f"ROUTER.md [{d}]: gelistete Seite {s} existiert nicht")
elif not s.startswith(f"knowledge/{d}/"):
fehler.append(f"ROUTER.md [{d}]: {s} gehört nicht zur Domäne {d}")
if not still:
for w in warnungen:
print(f"🟡 WARNUNG {w}")
for f in fehler:
print(f"🔴 FEHLER {f}")
if fehler:
print(f"\nvalidate: {len(fehler)} Fehler, {len(warnungen)} Warnungen — "
f"FAIL-CLOSED: erst beheben, dann weiterarbeiten.")
else:
extern_zusatz = (
f", {len(extern)} externe Quellen" if extern else ""
)
print(f"🟢 validate: 0 Fehler, {len(warnungen)} Warnungen — "
f"{len(seiten)} Seiten, {len(claims)} Claims, "
f"{len(register)} Quellen{extern_zusatz}.")
extern_kontext = {"register": extern, "anchors": anchors,
"orchestrators": orchestrators}
return fehler, warnungen, seiten, claims, register, router, extern_kontext
def build_index(seiten):
zeilen = ["# INDEX — Navigations-Map des Wissenstresors",
"",
"<!-- Generiert durch scripts/vault.py index — NICHT von Hand editieren. -->",
"<!-- Manuelle Audit-Map; für Abfragen zuerst vault.py query, dann Kandidatenseiten lesen. -->",
""]
nach_dom = {}
for rp, s in sorted(seiten.items()):
nach_dom.setdefault(s["fm"].get("domain", "?"), []).append((rp, s))
for dom in sorted(nach_dom):
zeilen.append(f"## {dom}")
zeilen.append("")
zeilen.append("| Seite | Typ | Status | Konfidenz | Stand | Titel |")
zeilen.append("|---|---|---|---|---|---|")
for rp, s in nach_dom[dom]:
fm = s["fm"]
name = Path(rp).name
zeilen.append(f"| [{name}]({rp}) | {fm.get('type','')} | {fm.get('status','')} "
f"| {fm.get('confidence','')} | {fm.get('stand','')} "
f"| {fm.get('title','')} |")
zeilen.append("")
return "\n".join(zeilen)
def cmd_index():
def arbeit():
fehler, _, seiten, *_ = cmd_validate(still=True)
if fehler:
print("🔴 index: abgebrochen — validate meldet Fehler (fail-closed). "
"Erst 'vault.py validate' grün bekommen.")
return 1
try:
_replace_files_transactionally({INDEX: build_index(seiten).encode("utf-8")})
except RollbackIncompleteError:
raise
except (OSError, RuntimeError, TypeError) as exc:
print(f"🔴 index: Schreiben fehlgeschlagen — {exc}")
return 1
print(f"🟢 index: {rel(INDEX)} neu erzeugt ({len(seiten)} Seiten).")
return 0
return _run_locked_mutation("index", arbeit)
def build_graph(seiten):
knoten, kanten = [], []
for rp, s in sorted(seiten.items()):
fm = s["fm"]
knoten.append({"id": rp, "titel": fm.get("title", ""), "typ": fm.get("type", ""),
"domaene": fm.get("domain", ""), "status": fm.get("status", ""),
"konfidenz": fm.get("confidence", ""), "stand": fm.get("stand", ""),
"begriffe": sorted(fm.get("concepts", [])),
"claims": sorted(c["id"] for c in s["claims"])})
for r in s["relationen"]:
kanten.append({"von": rp, "nach": r["ziel"], "typ": r["typ"]})
kanten.sort(key=lambda k: (k["von"], k["nach"], k["typ"]))
return {"profil": PROFIL, "knoten": knoten, "kanten": kanten}
def cmd_graph():
def arbeit():
fehler, _, seiten, *_ = cmd_validate(still=True)
if fehler:
print("🔴 graph: abgebrochen — validate meldet Fehler (fail-closed).")
return 1
g = build_graph(seiten)
inhalt = json.dumps(g, ensure_ascii=False, indent=2, sort_keys=True) + "\n"
try:
_replace_files_transactionally({GRAPH: inhalt.encode("utf-8")})
except RollbackIncompleteError:
raise
except (OSError, RuntimeError, TypeError) as exc:
print(f"🔴 graph: Schreiben fehlgeschlagen — {exc}")
return 1
print(f"🟢 graph: {rel(GRAPH)} abgeleitet — {len(g['knoten'])} Knoten, "
f"{len(g['kanten'])} Kanten. Kanten stammen nur aus validierten Seiten.")
return 0
return _run_locked_mutation("graph", arbeit)
def cmd_search(begriffe, mit_quellen=True):
"""Erschöpfende, deterministische Volltextsuche.
Ein Nicht-Treffer beweist nur lexikalische, nie semantische Abwesenheit.
Einen Negativbefund trägt allein die Vollsichtung (sweep)."""
try:
unsichere = _skill_symlinks() + _skill_hardlinks()
except OSError as exc:
print(f"🔴 search: Tresorbaum kann nicht vollständig geprüft werden — {exc}")
return 1
if unsichere or not _safe_directory(KNOWLEDGE):
print("🔴 search: unsichere Symlinks/Hardlinks oder knowledge-Grenze "
"— Suche fail-closed abgebrochen.")
return 1
if mit_quellen and (
not _safe_regular_file(REGISTER) or not _safe_regular_file(ROUTER)):
print("🔴 search: REGISTER.md/ROUTER.md fehlt oder ist kein sicheres "
"reguläres Tresor-Dokument.")
return 1
muster = re.compile("|".join(re.escape(b) for b in begriffe), re.IGNORECASE)
try:
dateien = list(iter_pages())
except OSError as exc:
print(f"🔴 search: Wissensseiten können nicht vollständig gelesen werden — {exc}")
return 1
if mit_quellen:
for extra in (REGISTER, ROUTER):
dateien.append(extra)
treffer = 0
for p in dateien:
for n, line in enumerate(read(p).split("\n"), 1):
if muster.search(line):
treffer += 1
print(f"{rel(p)}:{n}: {line.strip()[:160]}")
print(f"\nsearch: {treffer} Treffer für {begriffe} "
f"(erschöpfend über {len(dateien)} Dateien).")
if treffer == 0:
print("Kein Lexiktreffer: semantische Abwesenheit ist damit nicht "
"bewiesen. Einen Negativbefund trägt nur die Vollsichtung mit "
"Quittung: vault.py sweep \"<frage>\".")
return 0 if treffer else 1
def _query_base(query, state, *, manifest_digest=None, version=None,
errors=None, warnings=None):
return {
"schema": QUERY_SCHEMA,
"profile": PROFIL,
"retrieval": RETRIEVAL_PROFILE,
"state": state,
"query": query,
"vault": {
"version": version,
"manifest_sha256": manifest_digest,
},
"coverage": {
"retrieval_complete": False,
"semantic_coverage": "not_assessed",
"mode": "exhaustive_validated_claim_ranking",
"claims_scanned": 0,
# Seit hybrid-local/v2: wie gut das Ranking die Frage verstanden
# hat. Die Felder stehen in jedem Zustand, auch im Fehlerfall,
# damit ein Konsument nie auf einen fehlenden Schlüssel prüft.
"wortform": WORTFORM_PROFILE,
# None heißt: nicht bewertet. Nur 'candidates_found' und
# 'no_candidates' tragen eine Trefferstärke; ein Fehlerzustand
# ist kein "kein Kandidat".
"match_strength": None,
"term_coverage_percent": 0,
"query_terms": {
"content": [], "matched": [], "partial": [], "unmatched": [],
},
"candidates": {
"total": 0, "returned": 0,
"omitted_direct": 0, "omitted_context": 0,
},
"omitted_pages": [],
"omitted_pages_truncated": False,
"unknown_ids": [],
},
"fallback": {
"exhaustive_review_required": False,
"unknown_ids_only": False,
"reason": None,
"page_paths": [],
"page_paths_total": 0,
"sweep": None,
# Gegenstück zu page_paths: was ein Mensch AUSSERHALB des Bestands
# nachlesen müsste. Nur Hinweis, nie Ersatz für "Nicht im Bestand".
#
# Zwei getrennte Felder, weil sie zwei verschiedene Fragen
# beantworten: '…_available' ist das ANGEBOT (gibt es überhaupt
# aufgeführte Quellen?) und steht auch ohne --extern, weil der
# Antwort-Workflow genau dann entscheiden muss, ob Schritt 4c
# existiert. '…_used' ist das ERGEBNIS (wurde live gelesen?).
"external_lookup_available": False,
"external_source_ids": [],
"external_live_lookup_used": False,
"external_reason": None,
"external_document_paths": [],
},
"concepts": {"matched": [], "expanded": [], "partial": []},
# Externe Bezugsquellen stehen bewusst in einem eigenen Block und nie
# in 'evidence': ein externer Satz ist ein Zeiger, kein kuratierter
# Claim dieses Bestands. Der Top-Level-'state' bleibt eingefroren,
# damit bestehende Konsumenten nicht an einem neuen Wert brechen.
"external": {
"state": "not_requested",
"algorithm": EXTERN_RETRIEVAL_PROFILE,
"live": False,
"fetched_at": None,
"sources": [],
"hits": [],
"reason": None,
"notes": [],
"external_fingerprint": None,
},
"pages": [],
"evidence": [],
"warnings": sorted(set(warnings or [])),
"errors": list(errors or []),
"retrieval_fingerprint": None,
}
MELDUNG_MIT_SIGNATUR = ("Meldung enthält eine offensichtliche "
"Instruktionssignatur — Wortlaut nur in validate")
MELDUNG_EXTERN_MIT_SIGNATUR = ("Meldung enthält eine offensichtliche "
"Instruktionssignatur — Wortlaut nicht "
"ausgegeben")
MELDUNG_ORT_RE = re.compile(r"[\w./-]+(?::\d+)?")
# Ein Pfad in einer Meldung, auch in Bindestrichform: ein Token mit "/" oder
# mit einer Dateiendung. Gesucht wird tokenweise, linear auch bei langen
# Zeilen ohne Leerraum. Getrennt wird auch an ":" und "#", denn dahinter
# steht eine Zeilennummer oder ein Anker ("datei.md:3", "datei.md#L3").
MELDUNG_TRENNER_RE = re.compile(r"[\s'\"„“”‚‘’»«()\[\]{},;:#`<>!?|]+")
MELDUNG_DATEI_RE = re.compile(r"\.(?:md|markdown|txt|json)$", re.IGNORECASE)
MELDUNG_KENNUNG_RE = re.compile(r"[A-Z]-\d{4}(?![\w-])")
# So zitiert repr() nicht druckbaren Leerraum: \t, \xa0, \u2009 …
MELDUNG_ESCAPE_RE = re.compile(
r"\\(?:[tnrfv]|x[0-9a-fA-F]{2}|u[0-9a-fA-F]{4}|U[0-9a-fA-F]{8})")
# Grob getrennt bleibt ein Anker oder eine Query am Pfad
# ("a/b.md#ignore-all-previous-instructions", "…/suche?q=…"): Fein getrennt
# hätte das abgetrennte Stück weder "/" noch eine Endung.
MELDUNG_TRENNER_GROB_RE = re.compile(r"[\s'\"„“”‚‘’»«()\[\],;]+")
def _meldung_pfade(text):
"""Die Pfade einer Meldung: fein getrennt, auch an ":" und "#"
("datei.md:3"), und grob, mit Anker und Query am Pfad."""
for token in MELDUNG_TRENNER_RE.split(text):
token = token.strip(".")
if "/" in token or MELDUNG_DATEI_RE.search(token):
yield token
for token in MELDUNG_TRENNER_GROB_RE.split(text):
token = token.rstrip(":.")
if "/" in token or MELDUNG_DATEI_RE.search(token):
yield token
def _meldung_ohne_signatur(text, ersatz=MELDUNG_MIT_SIGNATUR):
"""Eine Meldung so, wie query und sweep sie ausgeben.
Fehler und Warnungen zitieren mitunter kuratierten Text (eine
Frontmatter-Zeile, eine Registerspalte). Trägt eine Meldung eine
Instruktionssignatur, ersetzt die Ausgabe sie ganz: Nur die Phrase zu
schwärzen ließe den Rest des zitierten Werts stehen, und das ist gerade
die Anweisung. Geprüft wird auch die Form, in der repr() nicht
druckbaren Leerraum zitiert ('ignore\\xa0all …'), und jeder Pfad nach der
Pfadregel (_pfad_mit_signatur). Stehen bleibt nur der Ort (Pfad,
optional mit Zeile), wenn die Meldung mit einem beginnt und er selbst
keine Signatur trägt, sonst eine führende Kennung (X-0001). validate behält den Wortlaut der Fehler
und Warnungen, damit die Stelle zu finden ist."""
if not isinstance(text, str) or not (
_hat_signatur(text)
or _hat_signatur(MELDUNG_ESCAPE_RE.sub(" ", text))
or any(_pfad_mit_signatur(pfad) for pfad in _meldung_pfade(text))):
return text
ort, trenner, _ = text.partition(": ")
if (trenner and MELDUNG_ORT_RE.fullmatch(ort)
and not _pfad_mit_signatur(ort)):
return f"{ort}: {ersatz}"
kennung = MELDUNG_KENNUNG_RE.match(text)
if kennung:
return f"{kennung.group(0)}: {ersatz}"
return ersatz
def _emit_query_json(result):
# Gilt für jede Ausgabe von query und sweep, auch im fail-closed-Pfad.
for feld in ("errors", "warnings"):
if isinstance(result.get(feld), list):
result[feld] = [_meldung_ohne_signatur(m) for m in result[feld]]
extern = result.get("external")
if isinstance(extern, dict):
if isinstance(extern.get("notes"), list):
extern["notes"] = [
_meldung_ohne_signatur(m, MELDUNG_EXTERN_MIT_SIGNATUR)
for m in extern["notes"]]
if "reason" in extern:
extern["reason"] = _meldung_ohne_signatur(
extern["reason"], MELDUNG_EXTERN_MIT_SIGNATUR)
rueckfall = result.get("fallback")
if isinstance(rueckfall, dict) and "external_reason" in rueckfall:
rueckfall["external_reason"] = _meldung_ohne_signatur(
rueckfall["external_reason"], MELDUNG_EXTERN_MIT_SIGNATUR)
print(json.dumps(
result, ensure_ascii=False, indent=2, sort_keys=True
))
def _load_released_query_snapshot(query):
"""Validierten, manifestgebundenen Query-Snapshot fail-closed puffern."""
if not isinstance(query, str) or not query.strip():
return None, _query_base(
query if isinstance(query, str) else "",
"invalid_query",
errors=["Frage darf nicht leer sein"],
)
if len(query) > MAX_QUERY_LENGTH:
return None, _query_base(
query, "invalid_query",
errors=[f"Frage ist länger als {MAX_QUERY_LENGTH} Zeichen"],
)
if any(ord(char) < 32 or ord(char) == 127 for char in query):
return None, _query_base(
query, "invalid_query",
errors=["Steuerzeichen/Zeilenumbrüche sind in Fragen verboten"],
)
if os.path.lexists(str(RELEASE_LOCK)):
return None, _query_base(
query, "vault_busy",
errors=["Release-/Recovery-Lock vorhanden; kein konsistenter Snapshot"],
)
if not _safe_regular_file(MANIFEST):
return None, _query_base(
query, "invalid_vault",
errors=["MANIFEST.sha256 fehlt oder ist nicht sicher lesbar"],
)
try:
manifest_digest = sha256_file(MANIFEST)
except OSError as exc:
return None, _query_base(
query, "invalid_vault",
errors=[f"Manifest kann nicht sicher gehasht werden: {exc}"],
)
manifest_errors, _ = _manifest_status()
if manifest_errors:
return None, _query_base(
query, "invalid_vault", manifest_digest=manifest_digest,
errors=manifest_errors,
)
(errors, warnings, pages, claims, register, _,
extern_kontext) = cmd_validate(still=True)
if errors:
return None, _query_base(
query, "invalid_vault", manifest_digest=manifest_digest,
errors=errors, warnings=warnings,
)
derived_errors = []
try:
if not _safe_regular_file(INDEX) or read(INDEX) != build_index(pages):
derived_errors.append("INDEX.md ist nicht konsistent mit dem Bestand")
expected_graph = (
json.dumps(build_graph(pages), ensure_ascii=False, indent=2,
sort_keys=True) + "\n"
)
if not _safe_regular_file(GRAPH) or read(GRAPH) != expected_graph:
derived_errors.append(
"graph/graph.json ist nicht konsistent mit dem Bestand"
)
except (OSError, UnicodeError) as exc:
derived_errors.append(f"Abgeleitete Artefakte sind nicht sicher lesbar: {exc}")
if derived_errors:
return None, _query_base(
query, "invalid_vault", manifest_digest=manifest_digest,
errors=derived_errors, warnings=warnings,
)
worlds, concepts, concept_errors = parse_concepts()
media, media_errors = parse_media_representations(register)
auxiliary_errors = concept_errors + media_errors
if auxiliary_errors:
return None, _query_base(
query, "invalid_vault", manifest_digest=manifest_digest,
errors=auxiliary_errors, warnings=warnings,
)
try:
version = read(VERSION).strip() if _safe_regular_file(VERSION) else None
except (OSError, UnicodeError):
version = None
if version is None or not VERSION_RE.fullmatch(version):
return None, _query_base(
query, "invalid_vault", manifest_digest=manifest_digest,
errors=["VERSION fehlt, ist unsicher oder kein SemVer"],
warnings=warnings,
)
# Nach dem vollständigen Parsen erneut gegen genau denselben Release prüfen.
manifest_errors_after, _ = _manifest_status()
try:
digest_after = sha256_file(MANIFEST)
except OSError as exc:
return None, _query_base(
query, "snapshot_changed", manifest_digest=manifest_digest,
version=version, errors=[f"Manifest änderte sich beim Lesen: {exc}"],
)
if (os.path.lexists(str(RELEASE_LOCK))
or digest_after != manifest_digest or manifest_errors_after):
reasons = manifest_errors_after or [
"Release-/Manifeststand änderte sich während der Abfrage"
]
return None, _query_base(
query, "snapshot_changed", manifest_digest=manifest_digest,
version=version, errors=reasons,
)
return {
"query": query,
"manifest_digest": manifest_digest,
"version": version,
"warnings": warnings,
"pages": pages,
"claims": claims,
"register": register,
"worlds": worlds,
"concepts": concepts,
"media": media,
"extern": extern_kontext,
}, None
def _stamm_phrase(norm_text, inhalt):
"""Wortstamm-Phrase, in der nur Inhaltswörter als Stamm stehen.
Ein Funktionswort bleibt wörtlich und markiert stehen. Ohne die Marke
träfe "sich" den Stamm von "Sicherung", "seit" den von "Seite" und
"wegen" den von "Weg": Ein Füllwort der Frage benennte dann einen
kuratierten Begriff, lieferte einen Anker und schaltete die
Pflicht-Vollsichtung ab.
"""
return " ".join(
_wortstamm(wort) if wort in inhalt else "=" + wort
for wort in norm_text.split()
)
def _match_concepts(query_norm, concepts, world=None, inhalt=None):
"""Begriffe über ihre kuratierten Benennungen finden: exakt, sonst Wortform.
Die exakte Stufe ist unverändert die aus hybrid-local/v1. Die
Wortform-Stufe füllt nur Lücken: eine Benennung, deren Wortstamm-Phrase
schon exakt getroffen wurde, wird nicht ein zweites Mal über eine andere
Schreibung einem weiteren Begriff zugeschlagen. Ohne diese Rangfolge
zöge "Regeln" neben dem exakt benannten Begriff auch jeden mit dem Alias
"Regel" aus einer anderen Welt herein.
Mehrdeutig ist eine Wortform nur über Weltgrenzen hinweg. Innerhalb einer
Welt wäre der Zustand unauflösbar, weil '--world' dort nichts trennt;
zwei Begriffe derselben Welt gelten dann beide als getroffen.
``inhalt`` sind die Inhaltstokens der Frage. Die Wortform-Stufe trifft
eine Benennung nur über sie: mindestens ein Inhaltswort muss die
Benennung tragen, und Funktionswörter zählen nur wörtlich. Die exakte
Stufe bleibt davon unberührt; als kuratierte Benennung ist auch ein
Homograph wie "Macht" weiterhin exakt auffindbar. Ohne ``inhalt`` gilt
jedes Wort als Inhaltswort.
"""
if inhalt is None:
inhalt = set(query_norm.split())
query_stamm = _stamm_phrase(query_norm, inhalt)
kandidaten = []
for concept_id, concept in sorted(concepts.items()):
if world is not None and concept.get("world") != world:
continue
labels = [concept.get("preferred", "")] + concept.get("aliases", [])
for label in labels:
normalized = _retrieval_norm(label)
if normalized:
label_inhalt = set(_inhaltstokens(label))
kandidaten.append((
concept_id, label, normalized,
_stamm_phrase(normalized, label_inhalt),
bool(label_inhalt),
))
phrase_matches = {}
matched_labels = {}
modes = {}
exakt_gedeckt = set()
for concept_id, label, normalized, stamm, _ in kandidaten:
if _phrase_present(query_norm, normalized):
phrase_matches.setdefault(normalized, []).append(concept_id)
matched_labels.setdefault(concept_id, []).append(label)
modes[concept_id] = "exact"
exakt_gedeckt.add(stamm)
ambiguous = {
phrase: sorted(ids)
for phrase, ids in sorted(phrase_matches.items())
if len(set(ids)) > 1
}
wortform_matches = {}
for concept_id, label, normalized, stamm, hat_inhalt in kandidaten:
if (concept_id in modes and modes[concept_id] == "exact"
or stamm in exakt_gedeckt
or not hat_inhalt
or not _phrase_present(query_stamm, stamm)):
continue
eintrag = wortform_matches.setdefault(stamm, {"ids": [], "label": label})
eintrag["ids"].append(concept_id)
matched_labels.setdefault(concept_id, []).append(label)
modes.setdefault(concept_id, "wortform")
for _, eintrag in sorted(wortform_matches.items()):
welten = {concepts[cid].get("world") for cid in eintrag["ids"]}
if len(welten) > 1:
ambiguous[_retrieval_norm(eintrag["label"])] = sorted(
set(eintrag["ids"]))
direct = sorted(matched_labels)
return direct, {
cid: sorted(set(labels), key=lambda value: (_retrieval_norm(value), value))
for cid, labels in matched_labels.items()
}, ambiguous, modes
def _match_concepts_teilweise(terms, concepts, direct, world=None):
"""Einwortige Benennungen, die einen Fragebegriff als Kompositumteil tragen.
Das ist ein Fingerzeig und kein Begriffstreffer: "Herkunft" berührt den
Alias "Herkunftsnachweis", benennt den Begriff aber nicht. Deshalb gibt es
hier weder Begriffserweiterung noch Definitions-Bonus, und die Stufe zählt
nie als Anker für die Trefferstärke.
"""
teilweise = {}
for concept_id, concept in sorted(concepts.items()):
if concept_id in direct:
continue
if world is not None and concept.get("world") != world:
continue
labels = [concept.get("preferred", "")] + concept.get("aliases", [])
for label in labels:
woerter = _retrieval_norm(label).split()
if len(woerter) != 1:
continue
for term in terms:
if _kompositum(term, woerter[0]):
teilweise.setdefault(concept_id, set()).add(term)
return {cid: sorted(terms) for cid, terms in sorted(teilweise.items())}
def _concept_expansion(concepts, direct):
"""Genau einen belegbaren Ontologie-Hop, hart begrenzt, ableiten."""
narrower = {}
for cid, concept in concepts.items():
for broader in concept.get("broader", []):
narrower.setdefault(broader, []).append(cid)
expansion = {}
for cid in direct:
concept = concepts[cid]
candidates = (
[(target, "broader", 55) for target in concept.get("broader", [])]
+ [(target, "narrower", 55) for target in narrower.get(cid, [])]
+ [(target, "related", 35) for target in concept.get("related", [])]
)
for target, relation, weight in sorted(candidates):
if target in direct or target not in concepts:
continue
previous = expansion.get(target)
proposal = {"id": target, "via": cid, "relation": relation, "weight": weight}
if previous is None or (
weight, cid, relation
) > (
previous["weight"], previous["via"], previous["relation"]
):
expansion[target] = proposal
return [
expansion[cid] for cid in sorted(expansion)[:MAX_CONCEPT_EXPANSIONS]
]
def _evidence_item(snapshot, path, claim, score, reasons,
role="retrieval_candidate"):
"""Ein Claim als Evidenz-Eintrag: dieselbe Form für query und sweep."""
fm = snapshot["pages"][path]["fm"]
# Präfix-Dispatch: X- steht im Extern-Register, S- im Quellen-
# register. Ohne diesen Zweig lieferte .get() still ein leeres
# dict, und der Claim bekäme eine leere Quellenangabe — ein
# Bug, der aussieht wie eine Antwort.
if claim.get("extern"):
extern_zeile = snapshot["extern"]["register"].get(
claim["quelle"], {})
source = {
"titel": extern_zeile.get("titel"),
"stand": extern_zeile.get("stand"),
"trust": extern_zeile.get("trust"),
"rechte": extern_zeile.get("rechte"),
"kind": "extern",
}
else:
source = dict(snapshot["register"].get(claim["quelle"], {}))
source["kind"] = "lokal"
item = {
"claim_id": claim["id"],
"role": role,
"page": path,
"page_status": fm.get("status"),
"page_confidence": fm.get("confidence"),
"page_reviewed_by": fm.get("geprueft_von"),
"page_reviewed_at": fm.get("geprueft_am"),
"page_trust_tier": _trust_tier(fm.get("geprueft_von")),
"score": int(score),
"reasons": sorted(set(reasons)),
"kind": claim["art"],
"text": claim["text"],
"source": _ohne_signatur({
"id": claim["quelle"],
"kind": source.get("kind"),
"title": source.get("titel"),
"stand": source.get("stand"),
"trust": source.get("trust"),
"rights": source.get("rechte"),
"locator": claim["fundstelle"],
}, ("title", "stand", "rights")),
"signals": [],
"media": None,
"anchor": None,
}
if claim["art"] == "Auslegung":
item["signals"].append("interpretation")
if fm.get("status") != "aktiv":
item["signals"].append(f"page_status:{fm.get('status')}")
if fm.get("confidence") == "niedrig":
item["signals"].append("low_confidence")
if source.get("trust") == "T3":
item["signals"].append("source_trust:T3")
# Nur die unterste Stufe wird als Signal geführt, analog zu
# source_trust:T3. Der Tier ist abgeleitet, geht nie in den Score
# ein und ist keine Zugriffskontrolle (OKF v0.2 §5.3).
if item["page_trust_tier"] == TIER_UNVERIFIED:
item["signals"].append(f"trust_tier:{TIER_UNVERIFIED}")
region_id = claim.get("region")
representation = snapshot["media"].get(claim["quelle"])
if region_id and representation:
region = representation["regions"].get(region_id, {})
item["media"] = {
"representation": representation["path"],
"media_type": representation["media_type"],
"region_id": region_id,
"region_kind": region.get("kind"),
"confidence": region.get("confidence"),
}
# Der Seitenpfad steht im Beleg; trägt er eine Signatur, trägt der Beleg
# das Signal (unten, zusammen mit dem Ankerpfad).
verdaechtig = _pfad_mit_signatur(path)
# Satzanker: wie bei Medienregionen wird nur die geprüfte
# Fundstelle ausgegeben, nie der externe Satz selbst. Der Wortlaut
# bleibt untrusted Quelldatum in der Ankerdatei.
anchor_id = claim.get("anker")
ankerdatei = snapshot["extern"]["anchors"].get(claim["quelle"])
if anchor_id and ankerdatei:
anker = ankerdatei["anchors"].get(anchor_id, {})
item["anchor"] = {
"anchor_id": anchor_id,
"document": anker.get("document"),
"sentence_index": anker.get("sentence_index"),
"block": anker.get("block"),
"text_sha256": anker.get("text_sha256"),
}
item["signals"].append("external_source")
# Der Pfad ist die Kennung der Fundstelle und bleibt stehen; trägt er
# eine Signatur, sagt das Signal es.
verdaechtig = verdaechtig or _pfad_mit_signatur(anker.get("document"))
# Das Signal steht einmal, auch wenn Seiten- und Ankerpfad es tragen.
if verdaechtig:
item["signals"].append("suspicious_instruction")
return item
def _seiten_relationen(pages):
"""Typisierte Kanten je Seite, in beiden Richtungen.
Wer eine Seite liest, sieht ihre ausgehenden Kanten im Frontmatter. Die
eingehenden sieht er dort nicht: dass eine neuere Fassung diese Seite
ersetzt oder eine andere ihr widerspricht, steht nur auf der anderen
Seite. Nach einer Vollsichtung gibt es zudem keinen Graph-Hop, der die
Nachbarin als Kandidaten hereinholte. Darum stehen beide Richtungen an
jeder ausgegebenen Seite: als Verweis, nie als Evidenz und ohne Einfluss
auf Rang oder Fingerabdruck.
"""
kanten = {path: {"outgoing": [], "incoming": []} for path in pages}
# Eine Nachbarseite, die Schritt 4 zu lesen verlangt, kann außerhalb von
# pages[] liegen; ihre Kante trägt deshalb ihre Markierung.
markiert = {path: _seite_mit_signatur(path, page)
for path, page in pages.items()}
def kante(typ, seite):
eintrag = {"type": typ, "page": seite}
if markiert.get(seite):
eintrag["suspicious_instruction"] = True
return eintrag
for path, page in sorted(pages.items()):
for relation in page["relationen"]:
kanten[path]["outgoing"].append(kante(relation["typ"], relation["ziel"]))
if relation["ziel"] in kanten:
kanten[relation["ziel"]]["incoming"].append(
kante(relation["typ"], path))
for eintrag in kanten.values():
for richtung in ("outgoing", "incoming"):
eintrag[richtung].sort(
key=lambda kante: (kante["type"], kante["page"]))
return kanten
def _seite_mit_signatur(pfad, seite):
"""Trägt eine Seite irgendwo eine Instruktionssignatur: im Titel, in einem
Tag, im Freitext oder im Pfad? Geprüft wird beim Ausgeben an den Feldern
selbst, damit auch eine Seite, die nicht aus lade_seiten kommt, ihre
Markierung trägt."""
fm = seite["fm"]
tags = fm.get("tags", [])
return bool(seite.get("freitext_signatur") or _hat_signatur(fm.get("title"))
or (isinstance(tags, list)
and any(_hat_signatur(tag) for tag in tags))
or _pfad_mit_signatur(pfad))
def _seite_markieren(eintrag, seite):
"""Markiert eine Seite, deren Signatur in keinem ausgegebenen Feld steht.
Den Freitext gibt die Engine nie aus, die Tags nicht in ``pages[]``, und
den Pfad braucht sie als Kennung. Die Seite liest der Agent aber ganz
(antworten.md, Schritt 4); also trägt sie die Markierung, wo immer sie
erscheint, auch als Ziel einer Kante (_seiten_relationen)."""
if _seite_mit_signatur(eintrag.get("path"), seite):
eintrag["suspicious_instruction"] = True
return eintrag
def _page_summary(snapshot, path, score, reasons, kanten):
fm = snapshot["pages"][path]["fm"]
return _seite_markieren(_ohne_signatur({
"path": path,
"title": fm.get("title"),
"domain": fm.get("domain"),
"status": fm.get("status"),
"confidence": fm.get("confidence"),
"stand": fm.get("stand"),
"reviewed_by": fm.get("geprueft_von"),
"reviewed_at": fm.get("geprueft_am"),
"trust_tier": _trust_tier(fm.get("geprueft_von")),
"score": int(score),
"reasons": sorted(set(reasons)),
"concepts": sorted(fm.get("concepts", [])),
"relations": kanten[path],
}, ("title",)), snapshot["pages"][path])
def _wortform_varianten(terms, tokenmengen):
"""Je Fragebegriff die Bestandstokens gleicher Wortform und die Kompositum-
Nachbarn. Einmal je Abfrage über das ganze Vokabular gerechnet, damit der
Abgleich je Claim nur noch ein Mengenschnitt ist."""
vokabular = set()
for tokens in tokenmengen:
vokabular |= tokens
staemme = {token: _wortstamm(token) for token in sorted(vokabular)}
# Zwei Verzeichnisse statt eines Vollscans je Fragebegriff. Gleiche
# Wortform heißt gleicher Stamm. Und ein Kompositumteil ist Kopf oder
# Schwanz mit mindestens KOMPOSITUM_MIN_TEIL Zeichen auf beiden Seiten
# der Naht: Zwei Formen, von denen eine Kopf der anderen ist, teilen also
# ihre ersten Zeichen, und beim Schwanz ihre letzten. Die Verzeichnisse
# liefern nur Anwärter; entschieden wird weiterhin von _kompositum_teil.
# Ohne sie wuchs die Abfrage mit Fragebegriffe mal Vokabular: 200
# Begriffe gegen 70.000 Tokens brauchten rund zehn Sekunden.
je_stamm, je_kopf, je_schwanz = {}, {}, {}
for token, token_stamm in staemme.items():
je_stamm.setdefault(token_stamm, set()).add(token)
for form in {token, token_stamm}:
if len(form) >= KOMPOSITUM_MIN_TEIL:
je_kopf.setdefault(
form[:KOMPOSITUM_MIN_TEIL], set()).add(token)
je_schwanz.setdefault(
form[-KOMPOSITUM_MIN_TEIL:], set()).add(token)
varianten = {}
for term in terms:
stamm = _wortstamm(term)
term_formen = {term, stamm}
gleiche = set(je_stamm.get(stamm, ())) - {term}
anwaerter = set()
for form in term_formen:
if len(form) >= KOMPOSITUM_MIN_TEIL:
anwaerter |= je_kopf.get(form[:KOMPOSITUM_MIN_TEIL], set())
anwaerter |= je_schwanz.get(form[-KOMPOSITUM_MIN_TEIL:], set())
teile = set()
for token in anwaerter:
if token == term or token in gleiche:
continue
token_formen = {token, staemme[token]}
if (_kompositum_teil(term_formen, token_formen)
or _kompositum_teil(token_formen, term_formen)):
teile.add(token)
varianten[term] = (gleiche, teile)
return varianten
def _term_treffer(term, tokens, varianten):
"""Beste Abgleichsstufe eines Fragebegriffs in einer Tokenmenge."""
if term in tokens:
return "token"
gleiche, teile = varianten[term]
if gleiche & tokens:
return "stem"
if teile & tokens:
return "compound"
return None
TERM_RANG = {"token": 3, "stem": 2, "compound": 1}
# Ganzzahlgewichte seit hybrid-local/v2. Die Zeile 'token' ist unverändert die
# aus v1; 'stem' und 'compound' liegen je Feld darunter. Die Staffel hält
# eine Ordnung fest, die sich in der Messung als tragend erwiesen hat, und
# zwar je Fragebegriff: ein Claim, der den Begriff selbst trägt (mindestens
# 12), steht vor einem, der denselben Begriff nur über Titel oder Tags
# seiner Seite erbt (höchstens 10), und beide vor dem reinen Graph-Nachbarn
# (5). Über mehrere Begriffe summiert sich Geerbtes, und die Seite eines
# direkt getroffenen kuratierten Begriffs hebt alle ihre Claims um 100: Das
# ist gewollt, steht aber über jedem einzelnen Worttreffer.
SEITEN_GEWICHTE = {
"token": {"title": 30, "tag": 24, "claim": 12},
"stem": {"title": 24, "tag": 20, "claim": 10},
"compound": {"title": 12, "tag": 10, "claim": 5},
}
CLAIM_GEWICHTE = {"token": 20, "stem": 16, "compound": 12}
KONTEXT_GEWICHTE = {"token": 10, "stem": 8, "compound": 6}
# Fingerzeig einer nur als Wortteil gestreiften Benennung, je Claim ihrer
# Seite. Bis v2 waren es 30 Punkte, also mehr als ein exakter eigener Treffer
# (20): Die ganze Begriffsseite füllte dann das Limit und der Claim, der das
# Fragewort selbst trug, fiel heraus. Seit v3 liegt der Fingerzeig wie jeder
# geerbte Treffer unter dem kleinsten eigenen.
FINGERZEIG_CLAIM = 10
# Reiner Graph-Nachbar: der kleinste Wert, unter jedem geerbten Treffer.
GRAPH_FUELLER = 5
def _sweep_stapel(seiten, groesse):
"""Seiten in feste Stapel packen. Eine Seite wird nie zerschnitten: ihr
Titel ist der Kontext, in dem ihre Claims lesbar sind."""
stapel, aktuell, zahl = [], [], 0
for path, claims in seiten:
if aktuell and zahl + len(claims) > groesse:
stapel.append(aktuell)
aktuell, zahl = [], 0
aktuell.append((path, claims))
zahl += len(claims)
if aktuell:
stapel.append(aktuell)
return stapel
def build_query_result(snapshot, world=None, limit=8):
"""Reines, ganzzahlig geranktes Hybrid-Retrieval über validierte Claims."""
query = snapshot["query"]
query_norm = _retrieval_norm(query)
# Eine Kennung hat ASCII-Ziffern. "C-0001" ist keine, sondern ein
# gewöhnliches Wort: Stünde sie unter unknown_ids, hieße das "gibt es
# nicht", obwohl es C-0001 gibt.
query_claim_ids = set(re.findall(
r"(?i)(?<![A-Z0-9])C-[0-9]{4}(?![A-Z0-9])", query))
query_claim_ids = {value.upper() for value in query_claim_ids}
query_source_ids = set(re.findall(
r"(?i)(?<![A-Z0-9])S-[0-9]{4}(?![A-Z0-9])", query))
query_source_ids = {value.upper() for value in query_source_ids}
query_concept_ids = set(re.findall(
r"(?i)(?<![A-Z0-9])B-[0-9]{4}(?![A-Z0-9])", query))
query_concept_ids = {value.upper() for value in query_concept_ids}
concepts = snapshot["concepts"]
worlds = snapshot["worlds"]
# Die Ziffern einer genannten ID sind kein Inhaltswort. Blieben sie
# stehen, gälte "C-0001" als Frage mit einem unverstandenen Begriff. Das
# gilt nur für IDs, die es im Bestand gibt: Eine vertippte oder fremde ID
# bleibt als unverstandenes Wort stehen, statt spurlos zu verschwinden.
bekannte_ids = (
{value for value in query_claim_ids if value in snapshot["claims"]}
| {value for value in query_source_ids
if value in snapshot["register"]}
| {value for value in query_concept_ids
if value in concepts
and (world is None or concepts[value]["world"] == world)}
)
id_ziffern = {value.split("-")[1] for value in bekannte_ids}
# Ob es eine genannte Kennung gibt, entscheidet das Script, nicht das
# Lesen: Das gehört ausdrücklich in die Ausgabe, nicht nur als
# ungetroffene Ziffernfolge.
unbekannte_ids = sorted(
(query_claim_ids | query_source_ids | query_concept_ids)
- bekannte_ids)
terms = sorted({
token for token in _inhaltstokens(query) if token not in id_ziffern
})
if world is not None and world not in worlds:
return _query_base(
query, "invalid_query",
manifest_digest=snapshot["manifest_digest"],
version=snapshot["version"],
errors=[f"Unbekannte Begriffswelt {world!r}"],
warnings=snapshot["warnings"],
)
direct, matched_labels, ambiguous, concept_modes = _match_concepts(
query_norm, concepts, world=world, inhalt=set(_inhaltstokens(query))
)
for concept_id in sorted(query_concept_ids):
if (concept_id in concepts
and (world is None or concepts[concept_id]["world"] == world)
and concept_id not in direct):
direct.append(concept_id)
matched_labels[concept_id] = [concept_id]
concept_modes[concept_id] = "id"
direct.sort()
if ambiguous:
details = [
f"{phrase!r} ist mehrdeutig: {', '.join(ids)}"
for phrase, ids in ambiguous.items()
]
return _query_base(
query, "ambiguous",
manifest_digest=snapshot["manifest_digest"],
version=snapshot["version"], errors=details,
warnings=snapshot["warnings"],
)
expansion = _concept_expansion(concepts, direct)
expanded_weights = {item["id"]: item["weight"] for item in expansion}
teilweise = _match_concepts_teilweise(terms, concepts, direct, world=world)
definitionen = {
concepts[cid]["definition_claim"]: cid
for cid in direct if concepts[cid].get("definition_claim")
}
# Fragebegriffe, die eine getroffene Benennung selbst trägt, je Begriff.
# Sie gelten als verstanden, auch wenn kein Claim sie wörtlich
# wiederholt — aber nur, solange der Begriff in der Ausgabe vertreten
# ist (siehe 'vertreten' unten).
begriff_terme = {}
for cid in direct:
staemme = set()
for label in matched_labels.get(cid, []):
staemme.update(_stamm_norm(label).split())
begriff_terme[cid] = {
term for term in terms if _wortstamm(term) in staemme}
pages = snapshot["pages"]
seiten_konzepte = {
path: set(page["fm"].get("concepts", []))
for path, page in pages.items()
}
seiten_tokens = {}
for path, page in sorted(pages.items()):
fm = page["fm"]
tag_tokens = set()
for tag in fm.get("tags", []):
tag_tokens.update(_inhaltstokens(tag))
seiten_tokens[path] = {
"title": set(_inhaltstokens(fm.get("title", ""))),
"tag": tag_tokens,
"claims": {
claim["id"]: set(_inhaltstokens(
f"{claim['text']} {claim['fundstelle']}"))
for claim in page["claims"]
},
}
varianten = _wortform_varianten(terms, (
tokens
for eintrag in seiten_tokens.values()
for tokens in [eintrag["title"], eintrag["tag"],
*eintrag["claims"].values()]
))
page_scores, page_reasons, starke_seiten = {}, {}, set()
seiten_begriffe = {}
for path, page in sorted(pages.items()):
fm = page["fm"]
tokens = seiten_tokens[path]
score, reasons, stark = 0, [], False
page_concepts = set(fm.get("concepts", []))
for cid in sorted(page_concepts & set(direct)):
score += 120
stark = True
reasons.append(f"concept:{cid}:direct")
for cid in sorted(page_concepts & set(expanded_weights)):
weight = expanded_weights[cid]
score += weight
stark = True
reasons.append(f"concept:{cid}:expanded:{weight}")
for cid in sorted(page_concepts & set(teilweise)):
score += 40
reasons.append(f"concept:{cid}:partial")
title_norm = _retrieval_norm(fm.get("title", ""))
claim_text = " ".join(
f"{claim['text']} {claim['fundstelle']}" for claim in page["claims"]
)
claim_tokens = set()
for einzeln in tokens["claims"].values():
claim_tokens |= einzeln
page_claim_ids = {claim["id"] for claim in page["claims"]}
page_source_ids = {claim["quelle"] for claim in page["claims"]}
for claim_id in sorted(query_claim_ids & page_claim_ids):
score += 180
stark = True
reasons.append(f"id:{claim_id}")
for source_id in sorted(query_source_ids & page_source_ids):
score += 100
stark = True
reasons.append(f"id:{source_id}")
claim_norm = _retrieval_norm(claim_text)
if query_norm and _phrase_present(title_norm, query_norm):
score += 80
stark = True
reasons.append("exact:title")
if query_norm and _phrase_present(claim_norm, query_norm):
score += 60
stark = True
reasons.append("exact:claim")
kopf = {}
for term in terms:
for feld, menge in (("title", tokens["title"]),
("tag", tokens["tag"]),
("claim", claim_tokens)):
stufe = _term_treffer(term, menge, varianten)
if stufe is None:
continue
score += SEITEN_GEWICHTE[stufe][feld]
reasons.append(f"{stufe}:{term}:{feld}")
if stufe != "compound":
stark = True
if feld != "claim" and (
TERM_RANG[stufe] > TERM_RANG.get(kopf.get(term), 0)):
kopf[term] = stufe
seiten_begriffe[path] = kopf
if score:
page_scores[path] = score
page_reasons[path] = reasons
if stark:
starke_seiten.add(path)
# Ein Graph-Hop ergänzt Kontext, bleibt aber niedriger gewichtet als
# jeder direkte Begriffs-/Lexikaltreffer. Er geht nur von Seiten aus, die
# mehr tragen als einen Kompositumteil: sonst zöge ein einziges zufällig
# passendes Wortende die ganze Nachbarschaft als Kandidaten herein.
graph_boost = {}
for source in sorted(starke_seiten):
for relation in pages[source]["relationen"]:
target = relation["ziel"]
graph_boost[target] = max(graph_boost.get(target, 0), 10)
for candidate, page in sorted(pages.items()):
if any(relation["ziel"] == source for relation in page["relationen"]):
graph_boost[candidate] = max(graph_boost.get(candidate, 0), 10)
for path, boost in sorted(graph_boost.items()):
if path not in pages:
continue
page_scores[path] = page_scores.get(path, 0) + boost
page_reasons.setdefault(path, []).append("graph:one-hop")
kandidaten = []
for path, page in sorted(pages.items()):
if path not in page_scores:
continue
fm = page["fm"]
page_concepts = set(fm.get("concepts", []))
concept_base = (
100 * len(page_concepts & set(direct))
+ sum(
expanded_weights[cid]
for cid in page_concepts & set(expanded_weights)
)
)
for claim in page["claims"]:
claim_norm = _retrieval_norm(
f"{claim['text']} {claim['fundstelle']}"
)
claim_tokens = seiten_tokens[path]["claims"][claim["id"]]
score = concept_base
reasons = []
# 'direkt' heißt: der Claim selbst trägt den Treffer. Alles
# andere ist Kontext seiner Seite und darf beim Kürzen fehlen.
direkt = False
eigene = {}
if concept_base:
reasons.append("concept-page")
elif page_concepts & set(teilweise):
score += FINGERZEIG_CLAIM
reasons.append("concept-page:partial")
if claim["id"] in definitionen:
score += 40
direkt = True
reasons.append(f"concept-definition:{definitionen[claim['id']]}")
if claim["id"] in query_claim_ids:
score += 240
direkt = True
reasons.append(f"id:{claim['id']}")
if claim["quelle"] in query_source_ids:
score += 140
direkt = True
reasons.append(f"id:{claim['quelle']}")
if query_norm and _phrase_present(claim_norm, query_norm):
score += 80
direkt = True
reasons.append("exact:claim")
for term in terms:
stufe = _term_treffer(term, claim_tokens, varianten)
if stufe is None:
continue
eigene[term] = stufe
score += CLAIM_GEWICHTE[stufe]
direkt = True
reasons.append(f"{stufe}:{term}")
# Kontext der Seite: ein Fragebegriff in Titel oder Tags hebt
# jeden Claim der Seite, der ihn nicht schon selbst trägt. Das
# ersetzt den pauschalen 'page-metadata'-Füller aus v1, der auch
# Geschwister eines einzelnen Zufallstreffers zu Kandidaten
# machte und damit echte Treffer aus dem Limit drängte.
for term, stufe in sorted(seiten_begriffe[path].items()):
if term in eigene:
continue
score += KONTEXT_GEWICHTE[stufe]
reasons.append(f"page-{stufe}:{term}")
if not score and path in graph_boost:
score = GRAPH_FUELLER
reasons.append("graph:one-hop")
if score <= 0:
continue
kandidaten.append({
"claim": claim, "path": path, "score": int(score),
"reasons": reasons, "direkt": direkt, "eigene": eigene,
})
def rangfolge(kandidat):
return (-kandidat["score"], kandidat["claim"]["id"], kandidat["path"])
kandidaten.sort(key=rangfolge)
gezeigt, gekuerzt = kandidaten[:limit], kandidaten[limit:]
# ---- Kontext weicht, Treffer nie. Ein Begriffstreffer hebt jeden Claim
# seiner Seite um 100 Punkte; ein wörtlicher Treffer auf einer anderen
# Seite bringt 20. Fragt jemand nach zwei Dingen, füllte das erste allein
# das Limit und das zweite verschwand, obwohl es im Bestand steht. Darum
# rückt für jeden Fragebegriff, den die Auswahl nicht trägt, der beste
# gekürzte Kandidat nach, der ihn selbst trägt — aber ausschließlich auf
# Kosten eines reinen Kontext-Kandidaten, also eines Claims, der nur über
# seine Seite in die Auswahl kam und dessen Seite auch ohne ihn vertreten
# bleibt. Ein Claim mit eigenem Treffer wird nie verdrängt.
#
# Die erste Fassung ließ den rangniedrigsten Kandidaten weichen, dessen
# Begriffe anderswo vertreten waren. Eine Kontrollfrage, die an dieser
# Regel nicht mitgebaut hatte, zeigte den Fehler: Füllwörter wie
# "stehen" und "mindestens" holten je ihren zufälligen Träger herein, und
# der Definitions-Claim auf Rang 6 flog dafür hinaus.
def getragen(kandidat):
begriffe = dict(seiten_begriffe.get(kandidat["path"], {}))
begriffe.update(kandidat["eigene"])
return {term for term, stufe in begriffe.items()
if TERM_RANG[stufe] >= TERM_RANG["stem"]}
def gehoert_zu(kandidat, cid):
"""Liegt der Kandidat auf einer Seite des Begriffs, oder definiert
er ihn?"""
return (cid in seiten_konzepte[kandidat["path"]]
or definitionen.get(kandidat["claim"]["id"]) == cid)
def vertreten(cid):
return any(gehoert_zu(k, cid) for k in gezeigt)
def nachruecken(nachruecker):
"""Der rangniedrigste reine Kontext-Kandidat weicht, wenn seine Seite
auch ohne ihn vertreten bleibt. Sonst bleibt die Rangfolge stehen."""
je_seite = {}
for kandidat in gezeigt:
je_seite[kandidat["path"]] = je_seite.get(kandidat["path"], 0) + 1
weichen = next(
(position for position in range(len(gezeigt) - 1, -1, -1)
if not gezeigt[position]["direkt"]
and je_seite[gezeigt[position]["path"]] > 1),
None,
)
if weichen is None:
return False
gekuerzt.remove(nachruecker)
gekuerzt.append(gezeigt[weichen])
gezeigt[weichen] = nachruecker
return True
# Zuerst die Begriffe. Nennt eine Frage zwei kuratierte Begriffe, füllte
# bis v2 die Seite des einen das Limit mit Kontext, die Seite des
# anderen fehlte samt Definitions-Claim — und das Ergebnis hieß trotzdem
# 'strong', weil eine getroffene Benennung pauschal als verstanden galt.
for cid in direct:
if vertreten(cid):
continue
nachruecker = next(
(k for k in gekuerzt if gehoert_zu(k, cid)), None)
if nachruecker is not None:
nachruecken(nachruecker)
def begriff_traegt(term):
return any(term in begriff_terme[cid] and vertreten(cid)
for cid in direct)
for term in terms:
if begriff_traegt(term) or any(term in getragen(k) for k in gezeigt):
continue
nachruecker = next(
(k for k in gekuerzt
if TERM_RANG.get(k["eigene"].get(term), 0) >= TERM_RANG["stem"]),
None,
)
if nachruecker is not None:
nachruecken(nachruecker)
gezeigt.sort(key=rangfolge)
gekuerzt.sort(key=rangfolge)
evidence = [
_evidence_item(snapshot, k["path"], k["claim"], k["score"],
k["reasons"])
for k in gezeigt
]
page_paths = sorted(
{item["page"] for item in evidence},
key=lambda path: (-page_scores.get(path, 0), path),
)
kanten = _seiten_relationen(pages)
page_results = [
_page_summary(snapshot, path, page_scores[path], page_reasons[path],
kanten)
for path in page_paths
]
# ---- Wie gut wurde die Frage verstanden? Gerechnet wird nur über das,
# was tatsächlich ausgegeben wird: ein Begriff, den allein ein gekürzter
# Kandidat trägt, hat das Modell nicht gesehen und gilt als ungetroffen.
term_stand = {term: 0 for term in terms}
for k in gezeigt:
for term, stufe in list(k["eigene"].items()) + list(
seiten_begriffe.get(k["path"], {}).items()):
term_stand[term] = max(term_stand[term], TERM_RANG[stufe])
# Eine getroffene Benennung trägt ihre Wörter nur, wenn der Begriff in
# der Ausgabe vertreten ist: durch einen Claim seiner Seite oder seinen
# Definitions-Claim. Sonst hat das Modell von ihm nichts gesehen.
vertretene = [cid for cid in direct if vertreten(cid)]
for cid in vertretene:
for term in begriff_terme[cid]:
term_stand[term] = TERM_RANG["token"]
# Ein Fragebegriff, den eine Benennung nur als Kompositumteil trägt, steht
# unter concepts.partial in der Ausgabe. Er ist damit ein Teiltreffer wie
# jeder andere und kein unbekanntes Wort. An der Stärke ändert das nichts:
# sie zählt allein die getroffenen Begriffe.
for begriffe in teilweise.values():
for term in begriffe:
term_stand[term] = max(term_stand[term], TERM_RANG["compound"])
getroffen = [term for term in terms if term_stand[term] >= 2]
teilgetroffen = [term for term in terms if term_stand[term] == 1]
ungetroffen = [term for term in terms if term_stand[term] == 0]
# Die ganze Frage als Wortfolge ist nur ein Anker, wenn dabei ein
# Inhaltswort getroffen ist: "nicht" oder "und" stehen wörtlich in
# vielen Claims, und die Abkürzung "IT" stünde sonst als englisches
# "it" in der Fundstelle "How it works".
anker = bool(vertretene) or any(
(reason == "exact:claim" and bool(getroffen))
or reason.startswith("id:")
for k in gezeigt for reason in k["reasons"]
)
# 'strong' heißt: nichts an der Frage blieb unverstanden. Ein direkt
# getroffener Begriff, von dem die Ausgabe nichts zeigt, ist unverstanden,
# auch wenn seine Benennung kein Inhaltswort beisteuert (ein per ID
# genannter Begriff, eine Benennung wie "Soll und Haben"). Dasselbe gilt
# für eine Kennung, die es nicht gibt: Ihre Ziffern können zufällig
# irgendwo stehen ("S-2026" und ein Datum), verstanden ist sie damit
# nicht.
unvertretene = [cid for cid in direct if cid not in vertretene]
if terms:
abdeckung = 100 * len(getroffen) // len(terms)
else:
abdeckung = 100 if anker else 0
if not evidence:
staerke = "none"
elif abdeckung == 100 and not unvertretene and not unbekannte_ids:
staerke = "strong"
elif anker or (len(getroffen) >= 2 and abdeckung >= 60):
staerke = "partial"
else:
staerke = "weak"
gezeigte_seiten = set(page_paths)
verdeckt = {}
# Ein unvertretener Begriff steht hier immer mit seiner Definitionsseite:
# Sein Definitions-Claim ist ein direkter Kandidat, und das Limit hat
# ihn abgeschnitten. Beim Kürzen der Liste bleibt sie erhalten (unten).
for k in gekuerzt:
if not k["direkt"] or k["path"] in gezeigte_seiten:
continue
eintrag = verdeckt.setdefault(k["path"], {
"path": k["path"], "claims": 0,
"best_claim": k["claim"]["id"], "best_score": k["score"],
})
eintrag["claims"] += 1
omitted_pages = sorted(
verdeckt.values(), key=lambda e: (-e["best_score"], e["path"]))
# Die Seite des Definitions-Claims eines unvertretenen Begriffs bleibt in
# der Liste, auch wenn sie gekürzt wird: Der Vertrag schickt den Agenten
# dorthin.
definitionsseiten = {
k["path"] for k in gekuerzt
if definitionen.get(k["claim"]["id"]) in unvertretene}
sichtbare_seiten = _sichtbare_seiten(
omitted_pages, definitionsseiten, MAX_OMITTED_PAGES)
# Schritt 4 liest auch diese Seiten; also tragen sie ihre Markierung.
for eintrag in sichtbare_seiten:
if eintrag["path"] in pages:
_seite_markieren(eintrag, pages[eintrag["path"]])
alle_seiten = sorted(
(path, [claim["id"] for claim in page["claims"]])
for path, page in pages.items() if page["claims"]
)
state = "candidates_found" if evidence else "no_candidates"
matched_output = [
{
"id": cid,
"world": concepts[cid]["world"],
"preferred": concepts[cid]["preferred"],
"matched_labels": matched_labels[cid],
"match": concept_modes.get(cid, "exact"),
"represented": cid in vertretene,
}
for cid in direct
]
expanded_output = [
{
**item,
"world": concepts[item["id"]]["world"],
"preferred": concepts[item["id"]]["preferred"],
}
for item in expansion
]
partial_output = [
{
"id": cid,
"world": concepts[cid]["world"],
"preferred": concepts[cid]["preferred"],
"terms": begriffe,
}
for cid, begriffe in teilweise.items()
]
fingerprint_data = {
"algorithm": RETRIEVAL_PROFILE,
"manifest": snapshot["manifest_digest"],
"query": query_norm,
"world": world,
"evidence": [
[item["claim_id"], item["score"]] for item in evidence
],
}
fingerprint = _sha256_bytes(json.dumps(
fingerprint_data, ensure_ascii=False, sort_keys=True,
separators=(",", ":"),
).encode("utf-8"))
result = _query_base(
query, state, manifest_digest=snapshot["manifest_digest"],
version=snapshot["version"], warnings=snapshot["warnings"],
)
schwach = staerke in {"none", "weak"}
# Nennt die Frage nichts als Kennungen, die es nicht gibt, ist die
# Antwort ein Befund des Scripts ("C-9999 gibt es nicht"); eine
# Vollsichtung fände nichts anderes. Nichts als heißt: keine vorhandene
# Kennung, auch keine B-ID aus einer anderen Begriffswelt, kein
# getroffener Begriff, und außer den Kennungen nur Wörter aus
# KENNUNG_RAHMENWOERTER. Ein Sachwort ("Mietminderung C-9999", "Waren
# C-9999") gehört zur Frage und will gesucht werden. Stehen die Ziffern
# irgendwo im Bestand, in einem Claim, einer Fundstelle, einem Titel oder
# Tag, kann etwas anderes gemeint sein als eine Kennung; auch dann bleibt
# die Vollsichtung Pflicht. Geprüft wird das am ganzen Bestand, nicht an
# der Ausgabe: Was das Limit abschneidet, steht trotzdem da.
ziffern_unbekannt = {kennung.split("-", 1)[1] for kennung in unbekannte_ids}
def ziffern_im_bestand():
# Jede Ziffernfolge des Bestands, auch als Wortteil ("C9991",
# "9992a", "9993er"): Auch dann kann etwas anderes gemeint sein.
folgen = set()
for eintrag in seiten_tokens.values():
for menge in (eintrag["title"], eintrag["tag"],
*eintrag["claims"].values()):
for token in menge:
folgen.update(re.findall(r"[0-9]+", token))
return bool(ziffern_unbekannt & folgen)
nur_unbekannte_kennung = (
bool(ziffern_unbekannt) and not bekannte_ids and not direct
and not any(kennung in concepts for kennung in unbekannte_ids)
and _nur_kennung_und_rahmen(query)
and not ziffern_im_bestand())
result.update({
"coverage": {
"retrieval_complete": True,
"semantic_coverage": "not_assessed",
"mode": "exhaustive_validated_claim_ranking",
"claims_scanned": len(snapshot["claims"]),
"wortform": WORTFORM_PROFILE,
"match_strength": staerke,
"term_coverage_percent": abdeckung,
"query_terms": {
"content": terms,
"matched": getroffen,
"partial": teilgetroffen,
"unmatched": ungetroffen,
},
"candidates": {
"total": len(kandidaten),
"returned": len(gezeigt),
"omitted_direct": sum(1 for k in gekuerzt if k["direkt"]),
"omitted_context": sum(
1 for k in gekuerzt if not k["direkt"]),
},
"omitted_pages": sichtbare_seiten,
"omitted_pages_truncated": len(omitted_pages) > MAX_OMITTED_PAGES,
"unknown_ids": unbekannte_ids,
},
"fallback": {
"exhaustive_review_required": (
schwach and not nur_unbekannte_kennung),
"unknown_ids_only": nur_unbekannte_kennung,
"reason": (
"unknown_ids_only" if nur_unbekannte_kennung
else "no_retrieval_candidates" if not evidence
else "weak_candidates_only" if schwach else None
),
"page_paths": sorted(snapshot["pages"])[:MAX_FALLBACK_SEITEN],
"page_paths_total": len(snapshot["pages"]),
# Der Aufwand der Vollsichtung steht hier, damit die Entscheidung
# dafür keine Schätzung ist.
"sweep": {
"claims": len(snapshot["claims"]),
"batch_size": SWEEP_STANDARD_GROESSE,
"batches": len(_sweep_stapel(
alle_seiten, SWEEP_STANDARD_GROESSE)),
},
"external_lookup_available": bool(
snapshot["extern"]["register"]),
# Welche Quellen aufgeführt sind, auch ohne --extern: Unterbleibt
# Schritt 4c, nennt die Antwort genau diese Kennungen.
"external_source_ids": sorted(snapshot["extern"]["register"]),
"external_live_lookup_used": False,
"external_reason": None,
"external_document_paths": [],
},
"concepts": {
"matched": matched_output,
"expanded": expanded_output,
"partial": partial_output,
},
"pages": page_results,
"evidence": evidence,
"retrieval_fingerprint": fingerprint,
})
return result
def _nur_kennung_und_rahmen(query):
"""Nennt die Frage außer Kennungen nur Wörter aus KENNUNG_RAHMENWOERTER?
Gelesen wird jedes Wort der Frage, nicht nur die Inhaltswörter des
Rankings: Dort fehlen Homographe wie "Waren", die hier Sachwörter sind.
Ein benennendes Substantiv zählt nur unmittelbar vor einer Kennung, ohne
Satzzeichen dazwischen ("die Quelle S-0099", nicht "ein Eintrag
(C-9999)"). Ein großgeschriebenes Wort mitten in der Frage ist im
Deutschen ein Substantiv und damit ein Sachwort ("Was ist ein Laut …?"),
ebenso jedes Wort hinter einem Artikel, auch kleingeschrieben ("was ist
ein laut in c-9999"). "laut" zählt nur als Präposition vor einer
Kennung, "bitte" nur am Anfang oder am Ende, ein Bindewort nur zwischen
zwei Kennungen. Ein Zeichen außer Buchstaben, Ziffern und gewöhnlichen
Satzzeichen ist ein Sachwort ("Was bedeutet § in C-9999?").
"""
text = KENNUNG_NOMEN_RE.sub(" ", query)
text = KENNUNG_ALLE_RE.sub(f" {KENNUNG_PLATZHALTER} ", text)
if KENNUNG_GLIEDERUNG_RE.sub("", WORT_RE.sub("", text)):
return False
woerter = []
for stelle, wort in enumerate(WORT_RE.findall(text)):
gross = stelle > 0 and wort[:1].isupper()
woerter.extend((teil, gross) for teil in _retrieval_norm(wort).split())
nur_woerter = [wort for wort, _ in woerter]
if KENNUNG_PLATZHALTER not in nur_woerter:
return False
letzte = len(nur_woerter) - 1
for stelle, (wort, gross) in enumerate(woerter):
if wort == KENNUNG_PLATZHALTER:
continue
if wort not in KENNUNG_RAHMENWOERTER or gross:
return False
davor = nur_woerter[stelle - 1] if stelle else None
danach = nur_woerter[stelle + 1:stelle + 3]
if davor in KENNUNG_DETERMINATIVE and wort not in KENNUNG_DETERMINATIVE:
return False
if wort == "laut" and not (stelle and (
danach[:1] == [KENNUNG_PLATZHALTER]
or (danach[:1] and danach[0] in KENNUNG_DETERMINATIVE
and danach[1:2] == [KENNUNG_PLATZHALTER]))):
return False
if wort == "bitte" and 0 < stelle < letzte:
return False
if wort in KENNUNG_BINDEWOERTER and not (
0 < stelle < letzte
and nur_woerter[stelle - 1] == KENNUNG_PLATZHALTER
and nur_woerter[stelle + 1] == KENNUNG_PLATZHALTER):
return False
return True
def _sichtbare_seiten(seiten, vorrang, grenze):
"""Die ersten `grenze` Einträge, Seiten aus `vorrang` zuerst.
`seiten` ist nach Rang sortiert, und die Auswahl behält diese Reihenfolge.
Eine Seite aus `vorrang` verdrängt nur eine ohne Vorrang, nie eine andere
mit Vorrang; erst wenn es mehr Vorrangseiten gibt als Plätze, entscheidet
unter ihnen der Rang.
"""
mit = [eintrag for eintrag in seiten if eintrag["path"] in vorrang]
ohne = [eintrag for eintrag in seiten if eintrag["path"] not in vorrang]
platz = max(0, grenze - len(mit))
gewaehlt = {eintrag["path"] for eintrag in mit[:grenze] + ohne[:platz]}
return [eintrag for eintrag in seiten if eintrag["path"] in gewaehlt]
def cmd_query(question_words, world=None, limit=8, extern=False,
quellen_filter=None):
query = " ".join(question_words)
snapshot, error = _load_released_query_snapshot(query)
if error is not None:
_emit_query_json(error)
return 1
result = build_query_result(snapshot, world=world, limit=limit)
# Ohne --extern verlässt kein Byte den Skill-Ordner. Das Flag macht am
# Aufruf sichtbar, dass hier bewusst eine Ausnahme von Regel 2
# (Vertrauen zur Abfragezeit) gemacht wird.
if extern and result["state"] not in {"candidates_found", "no_candidates"}:
# Eine lokale Abfrage, die so nicht auswertbar ist (unbekannte
# Begriffswelt, mehrdeutiger Alias), ist kein Anlass für Schritt 4c.
# Vorher wurde trotzdem extern gelesen, und das Ergebnis stand neben
# einem Envelope, der gar keine Auswertung enthielt.
result["external"]["state"] = "invalid_query"
result["external"]["reason"] = (
f"Die lokale Abfrage endete mit {result['state']!r}. Extern wurde "
f"nichts durchsucht — {EXTERN_KEIN_BEFUND}."
)
result["fallback"]["external_reason"] = result["external"]["reason"]
elif extern:
block = build_external_result(snapshot, query,
quellen_filter=quellen_filter)
gelesen = block.pop("documents_read", [])
result["external"] = block
# Das ERGEBNIS, nicht der Aufruf: wahr nur, wenn tatsächlich gelesen
# wurde. Das Flag --extern allein hat noch nichts nachgeschlagen —
# eine ungebundene oder nicht erreichbare Quelle liest kein Byte.
result["fallback"]["external_live_lookup_used"] = bool(block["live"])
result["fallback"]["external_reason"] = block.get("reason")
result["fallback"]["external_document_paths"] = gelesen
_emit_query_json(result)
if result["state"] in {"candidates_found", "no_candidates"}:
return 0
return 2
# ------------------------------------------------------- Vollsichtung
#
# 'query' ist die Abkürzung, 'sweep' ist die Zusage. Das Ranking kann eine
# Frage nur an Wörtern, Wortformen und kuratierten Begriffen erkennen; ob ein
# Claim sie der BEDEUTUNG nach beantwortet, kann nur beurteilen, wer ihn
# liest. Die Vollsichtung legt dem Modell deshalb jeden Claim des Umfangs vor,
# in festen Stapeln, und nimmt je Stapel ein Urteil entgegen.
#
# Was das Script dabei beweist und was nicht: Jeder Stapel trägt ein Siegel,
# das nur seine Ausgabe nennt. Eine Quittung mit allen Siegeln belegt, dass
# jeder Stapel für genau diesen Stand und genau diese Frage ausgegeben wurde
# und dass zu jedem ein ausdrückliches Urteil vorliegt. Sie belegt nicht, dass
# das Modell sorgfältig gelesen hat. Das Siegel schützt gegen Abkürzen und
# Vergessen, nicht gegen einen Leser, der vorsätzlich täuscht.
def _sweep_umfang(snapshot, domaenen, seiten):
"""Seiten im Umfang bestimmen. Ohne Filter ist es der ganze Bestand."""
pages = snapshot["pages"]
domaenen = sorted(set(domaenen or []))
seiten = sorted(set(seiten or []))
bekannte = {page["fm"].get("domain") for page in pages.values()}
fehler = [f"Unbekannte Domäne {name!r}" for name in domaenen
if name not in bekannte]
fehler += [f"Unbekannte Seite {pfad!r}" for pfad in seiten
if pfad not in pages]
if fehler:
return None, fehler
if domaenen or seiten:
gewaehlt = sorted(
pfad for pfad, page in pages.items()
if page["fm"].get("domain") in domaenen or pfad in seiten
)
else:
gewaehlt = sorted(pages)
belegt = [(pfad, pages[pfad]["claims"]) for pfad in gewaehlt
if pages[pfad]["claims"]]
im_umfang = sum(len(claims) for _, claims in belegt)
gesamt = len(snapshot["claims"])
return {
"seiten": belegt,
"ausgabe": {
"domains": domaenen,
"pages": seiten,
"pages_in_scope": len(belegt),
"claims_in_scope": im_umfang,
"claims_total": gesamt,
# 'complete' ist gezählt, nicht aus den Filtern geschlossen: ein
# Filter, der zufällig alles trifft, ist vollständig, und ein
# leerer Aufruf über einen leeren Bestand ebenfalls.
"complete": im_umfang == gesamt,
},
}, []
def _sweep_frage_norm(frage):
"""Die Frage, wie Siegel und Quittung sie binden.
Viel enger als die Normalisierung des Rankings. Dort dürfen "Maßen" und
"Massen", "<" und ">=", "C++" und "C#" zusammenfallen, weil ein Treffer
mehr nur ein Kandidat mehr ist. Ein Siegel dagegen sagt: Zu genau dieser
Frage wurde geurteilt. Gleich bleibt deshalb nur, was zwischen zwei
Aufrufen derselben Frage schwankt, ohne etwas zu bedeuten:
Groß-/Kleinschreibung, die Menge des Leerraums (nicht, ob zwischen zwei
Zeichen überhaupt welcher steht), die Art der Anführungszeichen und
Striche und Fragezeichen am Ende. Jedes andere Zeichen bleibt stehen,
auch Satzzeichen im Inneren.
Bis v0.14.0 fielen Satzzeichen an jedem Wortrand weg. Damit teilten sich
"a != b" und "a = b" ein Siegel, ebenso ".5" und "5" oder "!aktiv" und
"aktiv": Die Quittung der einen Frage galt für ihr Gegenteil.
"""
text = unicodedata.normalize("NFC", str(frage)).lower()
text = " ".join(text.translate(SWEEP_ZEICHEN_GLEICH).split())
# Eine Frage nur aus Fragezeichen bleibt, was sie ist.
return text.rstrip("? ") or text
def _sweep_siegel(snapshot, groesse, nummer, claim_ids):
"""Kurzer Digest über Stand, Frage, Stapelgröße, Nummer und Inhalt.
Die Frage geht normalisiert ein, damit Anführungszeichen und Leerraum
zwischen zwei Aufrufen nichts verschieben. Der Manifest-Digest bindet den
Wortlaut jedes Claims, ohne dass er hier noch einmal gehasht wird.
"""
daten = [SWEEP_SCHEMA, snapshot["manifest_digest"],
_sweep_frage_norm(snapshot["query"]), groesse, nummer,
list(claim_ids)]
return _sha256_bytes(json.dumps(
daten, ensure_ascii=False, separators=(",", ":"),
).encode("utf-8"))[:SWEEP_SIEGEL_LAENGE]
def _sweep_basis(query, state, snapshot=None, errors=None, warnings=None):
return {
"schema": SWEEP_SCHEMA,
"profile": PROFIL,
"state": state,
"query": query,
"vault": {
"version": snapshot["version"] if snapshot else None,
"manifest_sha256": (
snapshot["manifest_digest"] if snapshot else None),
},
"warnings": sorted(set(warnings or [])),
"errors": list(errors or []),
# In jedem Zustand vorhanden und fail-closed vorbelegt, wie bei
# 'query': Ein Konsument soll nie auf einen fehlenden Schlüssel
# prüfen müssen, um zu erfahren, dass nichts erlaubt ist.
"selected": [],
"evidence": [],
"abstention": {
"allowed": False,
"reason": {
"plan": "ein Plan ist keine Quittung",
"batch": "ein Stapel ist keine Quittung",
}.get(state, "ohne gültige, vollständige Quittung keine "
"Abstention"),
},
}
def build_sweep_result(snapshot, batch=None, receipt=None,
groesse=SWEEP_STANDARD_GROESSE, domaenen=None,
seiten=None):
"""Plan, einzelner Stapel oder Quittungsprüfung einer Vollsichtung."""
query = snapshot["query"]
warnings = snapshot["warnings"]
def abbruch(meldungen):
return _sweep_basis(query, "invalid_query", snapshot,
errors=meldungen, warnings=warnings)
if not SWEEP_MIN_GROESSE <= groesse <= SWEEP_MAX_GROESSE:
return abbruch([
f"--size muss zwischen {SWEEP_MIN_GROESSE} und "
f"{SWEEP_MAX_GROESSE} liegen"
])
if batch is not None and receipt is not None:
return abbruch(["--batch und --receipt schließen einander aus"])
umfang, fehler = _sweep_umfang(snapshot, domaenen, seiten)
if fehler:
return abbruch(fehler)
stapel = _sweep_stapel(umfang["seiten"], groesse)
stapel_ids = [
[claim["id"] for _, claims in gruppe for claim in claims]
for gruppe in stapel
]
siegel = [
_sweep_siegel(snapshot, groesse, nummer, ids)
for nummer, ids in enumerate(stapel_ids, 1)
]
kopf = {
"scope": umfang["ausgabe"],
"batch_size": groesse,
"batches_total": len(stapel),
}
if batch is None and receipt is None:
result = _sweep_basis(query, "plan", snapshot, warnings=warnings)
result.update(kopf)
result["batches"] = [
{
"batch": nummer,
"claims": len(ids),
"pages": len(gruppe),
"first_claim": ids[0],
"last_claim": ids[-1],
}
for nummer, (gruppe, ids) in enumerate(zip(stapel, stapel_ids), 1)
]
return result
if batch is not None:
if not 1 <= batch <= len(stapel):
return abbruch([
f"--batch {batch} liegt außerhalb von 1 bis {len(stapel)}"
])
gruppe = stapel[batch - 1]
result = _sweep_basis(query, "batch", snapshot, warnings=warnings)
result.update(kopf)
result["batch"] = batch
# Jeder Stapel wird ganz gelesen: Titel und Tags mit
# Instruktionssignatur stehen deshalb nicht darin (_ohne_signatur),
# und eine Signatur im Freitext markiert die Seite (_seite_markieren).
result["pages"] = [
_seite_markieren(_ohne_signatur({
"path": pfad,
"title": snapshot["pages"][pfad]["fm"].get("title"),
"domain": snapshot["pages"][pfad]["fm"].get("domain"),
"status": snapshot["pages"][pfad]["fm"].get("status"),
"stand": snapshot["pages"][pfad]["fm"].get("stand"),
"tags": list(snapshot["pages"][pfad]["fm"].get("tags", [])),
"claims": [
{
"claim_id": claim["id"],
"kind": claim["art"],
"source_id": claim["quelle"],
"text": claim["text"],
}
for claim in claims
],
}, ("title", "tags")), snapshot["pages"][pfad])
for pfad, claims in gruppe
]
result["seal"] = siegel[batch - 1]
return result
# ---- Quittung. Jeder Fehler ist fail-closed: ohne vollständige,
# stimmige Quittung gibt es weder Evidenz noch eine erlaubte Abstention.
urteile, meldungen = {}, []
for eintrag in receipt:
treffer = SWEEP_QUITTUNG_RE.fullmatch(eintrag)
if not treffer:
meldungen.append(
f"Quittungseintrag {eintrag!r} hat nicht die Form "
f"<stapel>:<siegel>=<C-nnnn,…|->"
)
continue
nummer = int(treffer.group(1))
gewaehlt = ([] if treffer.group(3) == "-"
else treffer.group(3).split(","))
if nummer in urteile:
meldungen.append(f"Stapel {nummer} ist doppelt quittiert")
continue
if not 1 <= nummer <= len(stapel):
meldungen.append(
f"Stapel {nummer} gibt es in diesem Umfang nicht "
f"(1 bis {len(stapel)})"
)
continue
if treffer.group(2) != siegel[nummer - 1]:
meldungen.append(
f"Stapel {nummer}: Siegel gehört nicht zu diesem Stand, "
f"dieser Frage, dieser Stapelgröße oder diesem Umfang"
)
continue
fremde = sorted(set(gewaehlt) - set(stapel_ids[nummer - 1]))
if fremde:
meldungen.append(
f"Stapel {nummer}: {', '.join(fremde)} steht nicht in "
f"diesem Stapel"
)
continue
urteile[nummer] = sorted(set(gewaehlt))
fehlend = [nummer for nummer in range(1, len(stapel) + 1)
if nummer not in urteile]
gesichtet = sum(len(stapel_ids[nummer - 1]) for nummer in urteile)
coverage = {
"claims_total": umfang["ausgabe"]["claims_total"],
"claims_in_scope": umfang["ausgabe"]["claims_in_scope"],
"claims_swept": gesichtet,
"batches_total": len(stapel),
"batches_confirmed": len(urteile),
"scope_complete": umfang["ausgabe"]["complete"],
"semantic_coverage": "not_assessed",
}
if meldungen or fehlend:
state = "invalid_receipt" if meldungen else "sweep_incomplete"
result = _sweep_basis(query, state, snapshot, errors=meldungen,
warnings=warnings)
result.update(kopf)
result.update({
"coverage": coverage,
"missing_batches": fehlend,
"selected": [],
"evidence": [],
"pages": [],
"abstention": {
"allowed": False,
"reason": (
"Quittung ist fehlerhaft" if meldungen
else "nicht jeder Stapel ist quittiert"),
},
"sweep_fingerprint": None,
})
return result
ausgewaehlt = sorted(
claim_id for ids in urteile.values() for claim_id in ids)
claim_seite = {
claim["id"]: (pfad, claim)
for pfad, claims in umfang["seiten"] for claim in claims
}
evidence = [
_evidence_item(snapshot, claim_seite[claim_id][0],
claim_seite[claim_id][1], 0, ["sweep:selected"],
role="sweep_selected")
for claim_id in ausgewaehlt
]
coverage["semantic_coverage"] = "swept"
vollstaendig = umfang["ausgabe"]["complete"]
# Die Kanten des ganzen Bestands, nicht nur des Umfangs: die Nachfolgerin
# einer gewählten Seite kann außerhalb eines eingeschränkten Umfangs liegen.
kanten = _seiten_relationen(snapshot["pages"])
fingerprint = _sha256_bytes(json.dumps({
"schema": SWEEP_SCHEMA,
"manifest": snapshot["manifest_digest"],
"query": _sweep_frage_norm(query),
"batch_size": groesse,
"seals": siegel,
"selected": ausgewaehlt,
}, ensure_ascii=False, sort_keys=True,
separators=(",", ":")).encode("utf-8"))
result = _sweep_basis(query, "sweep_complete", snapshot,
warnings=warnings)
result.update(kopf)
result.update({
"coverage": coverage,
"missing_batches": [],
"selected": ausgewaehlt,
"evidence": evidence,
"pages": [
_page_summary(snapshot, pfad, 0, ["sweep:selected"], kanten)
for pfad in sorted({item["page"] for item in evidence})
],
# 'allowed' ist die mechanische Vorbedingung, kein Befund: ob die
# ausgewählten Claims die Frage decken, beurteilt das Modell. Ein
# eingeschränkter Umfang erlaubt nie ein "Nicht im Bestand", nur ein
# "in diesem Umfang nicht gefunden".
"abstention": {
"allowed": vollstaendig,
"reason": (
"jeder Claim des Bestands wurde vorgelegt und je Stapel "
"quittiert"
if vollstaendig else
"Umfang ist eingeschränkt: nur 'in diesem Umfang nicht "
"gefunden' ist gedeckt, nicht 'Nicht im Bestand'"),
},
"sweep_fingerprint": fingerprint,
})
return result
def cmd_sweep(question_words, batch=None, receipt=None,
groesse=SWEEP_STANDARD_GROESSE, domaenen=None, seiten=None):
query = " ".join(question_words)
if not query.strip():
_emit_query_json(_sweep_basis(query, "invalid_query", errors=[
"Die Frage fehlt. Sie steht vor --receipt: der Schalter nimmt "
"alle folgenden Wörter als Quittungseinträge."
]))
return 2
snapshot, error = _load_released_query_snapshot(query)
if error is not None:
# Dieselbe fail-closed-Sperre wie bei 'query': ohne grünen,
# manifestierten Stand wird kein einziger Claim vorgelegt.
_emit_query_json(_sweep_basis(
query, error["state"], errors=error["errors"],
warnings=error["warnings"],
))
return 1
result = build_sweep_result(
snapshot, batch=batch, receipt=receipt, groesse=groesse,
domaenen=domaenen, seiten=seiten,
)
_emit_query_json(result)
if result["state"] in {"plan", "batch", "sweep_complete"}:
return 0
return 2
def cmd_extern(aktion, xid=None, pfad=None):
"""Aufgeführte externe Bezugsquellen anzeigen und maschinenlokal binden."""
register, fehler = parse_extern_register()
for eintrag in fehler:
print(f"🔴 FEHLER {eintrag}")
if fehler:
return 1
bindung, bindungsfehler = parse_bindung()
for eintrag in bindungsfehler:
print(f"🔴 FEHLER {eintrag}")
if bindungsfehler:
return 1
if aktion == "list":
if not register:
print(f"🟡 extern: {rel(EXTERN_REGISTER)} führt keine Quelle. "
f"Erreichbar ist ausschließlich, was dort namentlich steht.")
return 0
print(f"extern: {len(register)} aufgeführte Bezugsquelle(n)")
for kennung in sorted(register):
zeile = register[kennung]
status = _extern_quelle_status(kennung, zeile, bindung)
if status["modus"] == "netz":
ampel, wo = "🟢", f"Netz {zeile['ziel']}"
if not _netz_erlaubt():
ampel, wo = "🟡", f"{wo} ({EXTERN_OFFLINE_ENV} gesetzt)"
elif status["modus"] == "lokal":
ampel, wo = "🟢", f"lokal {status['wurzel']}"
else:
ampel, wo = "🟡", f"ungebunden — {status['grund']}"
print(f" {ampel} {kennung} {zeile['art']:<16} {zeile['titel']}")
print(f" {wo}")
return 0
if xid not in register:
print(f"🔴 extern: {xid!r} steht nicht in {rel(EXTERN_REGISTER)} — "
f"eine nicht aufgeführte Quelle wird nie erreicht")
return 1
if register[xid]["ziel"] != "-":
print(f"🔴 extern: {xid} ist eine Netzquelle und schon durch ihre "
f"Registrierung gebunden; eine Maschinenbindung gibt es dafür nicht")
return 1
if aktion == "bind":
wurzel, _, grund = _resolve_external_root(pfad)
if grund:
print(f"🔴 extern: Bindungswurzel abgelehnt — {grund}")
return 1
eintraege = [
{"key": bindung["bindings"][k]["key"], "source_id": k,
"root": bindung["bindings"][k]["root"],
"bound_at": bindung["bindings"][k]["bound_at"]}
for k in sorted(bindung["bindings"]) if k != xid
]
# Überlappungssperre: zwei Wurzeln dürfen einander nicht enthalten,
# sonst wäre nicht mehr entscheidbar, welche Quelle ein Dokument trägt.
for vorhanden in eintraege:
andere, _, fehlgrund = _resolve_external_root(vorhanden["root"])
if fehlgrund:
continue
if _resolved_within(wurzel, andere) or _resolved_within(andere, wurzel):
print(f"🔴 extern: Wurzel überlappt mit {vorhanden['source_id']} "
f"({vorhanden['root']})")
return 1
eintraege.append({"key": register[xid]["key"], "source_id": xid,
"root": str(wurzel),
"bound_at": date.today().isoformat()})
eintraege.sort(key=lambda e: e["source_id"])
elif aktion == "unbind":
eintraege = [
{"key": bindung["bindings"][k]["key"], "source_id": k,
"root": bindung["bindings"][k]["root"],
"bound_at": bindung["bindings"][k]["bound_at"]}
for k in sorted(bindung["bindings"]) if k != xid
]
else:
print(f"🔴 extern: unbekannte Aktion {aktion!r}")
return 1
inhalt = json.dumps(
{"schema": BINDING_SCHEMA, "bindings": eintraege,
"cache_ttl_seconds": bindung["cache_ttl_seconds"]},
ensure_ascii=False, indent=2, sort_keys=True) + "\n"
sicher, grund = _safe_output_target(BINDUNG)
if not sicher:
print(f"🔴 extern: unsicheres Schreibziel — {grund}")
return 1
try:
_replace_files_transactionally({BINDUNG: inhalt.encode("utf-8")})
except (OSError, RuntimeError, TypeError) as exc:
print(f"🔴 extern: Schreiben fehlgeschlagen — {exc}")
return 1
print(f"🟢 extern: {xid} {'gebunden an ' + str(pfad) if aktion == 'bind' else 'gelöst'} "
f"— {rel(BINDUNG)} steht bewusst außerhalb des Manifests")
return 0
def cmd_anchor_template(xid, dokument):
"""Sätze eines externen Dokuments mit Index und Digest ausgeben.
Nicht schreibend. Das Modell WÄHLT einen Satz aus, statt Zeilen zu zählen —
die Zerlegung und das Hashen sind deterministische Skriptarbeit.
"""
register, fehler = parse_extern_register()
if fehler or xid not in register:
print(json.dumps({
"schema": ANCHORS_SCHEMA, "state": "invalid_source",
"errors": fehler or [f"{xid} steht nicht in {rel(EXTERN_REGISTER)}"],
}, ensure_ascii=False, indent=2, sort_keys=True))
return 1
bindung, _ = parse_bindung()
status = _extern_quelle_status(xid, register[xid], bindung)
if status["modus"] == "unbound":
print(json.dumps({
"schema": ANCHORS_SCHEMA, "state": "not_bound",
"errors": [status["grund"]],
}, ensure_ascii=False, indent=2, sort_keys=True))
return 1
# Auch dieser Abruf gehört ins Herkunftsprotokoll; vorher ging die Liste
# verloren, und ein Netzabruf von anchor-template stand nirgends.
protokoll = []
text, digest, grund = _extern_dokument_text(
status, dokument, bindung["cache_ttl_seconds"], xid, protokoll)
for meldung in _log_abrufe(protokoll):
# stdout trägt das Gerüst, das in eine strikte Ankerdatei wandert;
# ein zusätzliches Feld bräche deren Schema. Die Meldung geht nach
# stderr.
print(f"🟡 Herkunftsprotokoll unvollständig: {meldung}",
file=sys.stderr)
if grund:
print(json.dumps({
"schema": ANCHORS_SCHEMA, "state": "unreachable",
"errors": [f"{dokument}: {grund}"],
}, ensure_ascii=False, indent=2, sort_keys=True))
return 1
anker = []
for index, art, satz in _saetze(text):
anker.append({
"id": f"A-{index:04d}",
"document": dokument,
"document_sha256": digest,
"sentence_index": index,
"block": art,
"locator": "AUSFÜLLEN",
"text": satz,
"text_sha256": _satz_digest(satz),
"suspicious_instruction": bool(PROMPT_INJECTION_RE.search(satz)),
})
print(json.dumps({
"schema": ANCHORS_SCHEMA,
"source_id": xid,
"source_kind": register[xid]["art"],
"segmentation": SEGMENTATION_PROFILE,
"language": "de",
"extractor": {"kind": "human", "name": "AUSFÜLLEN", "version": "1"},
"verified": False,
"anchors": anker,
}, ensure_ascii=False, indent=2, sort_keys=True))
return 0
def cmd_orchestrator_template(xid):
"""Katalog-Gerüst für einen externen Markdown-Baum ausgeben.
Alle Zahlenfelder sind nachrechenbar und kommen aus dem Script; ``title``,
``summary`` und ``tags`` bleiben leer und sind Modellarbeit. Genau diese
Trennlinie ist später der Prüfpunkt.
"""
register, fehler = parse_extern_register()
if fehler or xid not in register:
print(json.dumps({
"schema": ORCHESTRATOR_SCHEMA, "state": "invalid_source",
"errors": fehler or [f"{xid} steht nicht in {rel(EXTERN_REGISTER)}"],
}, ensure_ascii=False, indent=2, sort_keys=True))
return 1
if register[xid]["art"] != "markdown-tree":
print(json.dumps({
"schema": ORCHESTRATOR_SCHEMA, "state": "invalid_source",
"errors": [f"{xid} ist kein markdown-tree — ein fremder Tresor "
f"bringt seine Claims schon mit"],
}, ensure_ascii=False, indent=2, sort_keys=True))
return 1
bindung, _ = parse_bindung()
status = _extern_quelle_status(xid, register[xid], bindung)
if status["modus"] != "lokal":
print(json.dumps({
"schema": ORCHESTRATOR_SCHEMA, "state": "not_bound",
"errors": [status["grund"] or
"ein Katalog entsteht aus einem lokal gebundenen Baum"],
}, ensure_ascii=False, indent=2, sort_keys=True))
return 1
dokumente, zustand, grund = _extern_dokumente(
status["wurzel"], status["anker"])
if grund:
# Früher hieß hier jeder Fehler budget_exceeded, auch eine Sonderdatei
# oder ein unlesbares Dokument. Der Zustand nennt jetzt die Ursache.
print(json.dumps({
"schema": ORCHESTRATOR_SCHEMA, "state": zustand,
"errors": [grund],
}, ensure_ascii=False, indent=2, sort_keys=True))
return 1
eintraege = []
for dok in dokumente:
saetze = _saetze(dok["text"])
haeufigkeit = {}
for _, _, satz in saetze:
for token in _retrieval_tokens(satz):
haeufigkeit[token] = haeufigkeit.get(token, 0) + 1
top = sorted(haeufigkeit.items(), key=lambda e: (-e[1], e[0]))
eintraege.append({
"path": dok["path"],
"sha256": dok["sha256"],
"title": "AUSFÜLLEN",
"summary": "",
"tags": [],
"sentence_count": len(saetze),
"token_count": sum(haeufigkeit.values()),
"top_tokens": [token for token, _ in top[:MAX_EXTERN_TOP_TOKENS]],
})
fingerprint = _sha256_bytes("".join(
f"{dok['path']}\0{dok['sha256']}\n" for dok in dokumente
).encode("utf-8"))
print(json.dumps({
"schema": ORCHESTRATOR_SCHEMA,
"source_id": xid,
"segmentation": SEGMENTATION_PROFILE,
"generated_from_sha256": fingerprint,
"document_count": len(eintraege),
"documents": eintraege,
}, ensure_ascii=False, indent=2, sort_keys=True))
return 0
def cmd_media_template(source_id):
"""Nicht schreibendes JSON-Gerüst für eine registrierte Medienquelle."""
register, errors = parse_register()
if errors or source_id not in register:
result = {
"schema": MEDIA_SCHEMA,
"state": "invalid_source",
"errors": errors or [f"Quelle {source_id!r} fehlt im REGISTER"],
}
print(json.dumps(result, ensure_ascii=False, indent=2, sort_keys=True))
return 1
entry = register[source_id]
source_path, path_error = _safe_relative_path(ROOT, entry["ablage"])
expected_type = (
MEDIA_TYPES.get(source_path.suffix.lower()) if source_path else None
)
if (path_error or not expected_type or not _safe_regular_file(source_path)
or sha256_file(source_path) != entry["hash"]
or not _media_signature_matches(source_path, expected_type)):
result = {
"schema": MEDIA_SCHEMA,
"state": "invalid_source",
"errors": [
path_error or
"Quelle fehlt, Hash/Signatur weicht ab oder Format ist nicht erlaubt"
],
}
print(json.dumps(result, ensure_ascii=False, indent=2, sort_keys=True))
return 1
template = {
"schema": MEDIA_SCHEMA,
"source_id": source_id,
"source_sha256": entry["hash"],
"media_type": expected_type,
"language": "und",
"extractor": {
"kind": "human",
"name": "AUSFÜLLEN",
"version": "AUSFÜLLEN",
},
"verified": False,
"alt_text": "AUSFÜLLEN",
"regions": [{
"id": "R-0001",
"kind": "other",
"locator": "AUSFÜLLEN",
"text": "AUSFÜLLEN",
"confidence": 0,
"bbox": None,
"suspicious_instruction": False,
}],
}
print(json.dumps(template, ensure_ascii=False, indent=2, sort_keys=True))
return 0
# ------------------------------------------- Externe Bezugsquellen
#
# Grundsatz: Eine aufgeführte Bezugsquelle ist KEINE Internetrecherche. Es gibt
# keine Suche, keinen Suchendpunkt und kein Folgen von Links aus Inhalten —
# erreichbar ist ausschließlich, was namentlich in sources/EXTERN.md steht und
# damit über MANIFEST.sha256 gepinnt ist. Deshalb wird eine aufgeführte
# Netzquelle behandelt wie eine interne Quelle, und deshalb ist jeder Abruf im
# Log nachlesbar.
#
# Zweite Grundregel: Auf dem Default-Query-Pfad passiert nichts davon. Ohne
# --extern verlässt kein Byte den Skill-Ordner, weder zur Platte noch ins Netz.
def _extern_cache_dir(xid):
"""TTL-Abzug außerhalb des Skill-Ordners.
Innerhalb von ROOT liefe jeder Cache-Eintrag durch den Dateiart-Walk
(_skill_fremdartefakte) und den Manifest-Walk (_tracked_files) und
verunreinigte das Artefakt. Der Cache ist flüchtige Maschinensache.
"""
basis = os.environ.get("XDG_CACHE_HOME") or os.path.join(
os.path.expanduser("~"), ".cache")
return Path(basis) / "skillsafe" / ROOT.name / xid
def _resolve_external_root(roh):
"""Gebundene externe Wurzel fail-closed auflösen.
Rückgabe: ``(pfad, anker, None)`` oder ``(None, None, grund)``. ``anker``
ist ``(st_dev, st_ino)`` und wird bei jeder Datei erneut geprüft, damit ein
unter der Hand ausgetauschter Mount auffällt.
Dies ist die einzige Stelle im System, an der ein absoluter Pfad zulässig
ist. Die Tresorhelfer bleiben unverändert auf ROOT festgenagelt; hier
entsteht ein zweites, gleich strenges Confinement.
"""
if not isinstance(roh, str) or not roh.strip():
return None, None, "Bindungswurzel fehlt"
wert = roh.strip()
if wert != roh:
return None, None, "führende oder abschließende Leerzeichen sind verboten"
if any(ord(z) < 32 or ord(z) == 127 for z in wert):
return None, None, "Steuerzeichen sind in Pfaden verboten"
if not _utf8_pfad(wert):
# Ein einzelnes Surrogat aus der Bindungsdatei endete sonst in einem
# UnicodeEncodeError — auch bei 'extern list', das nur anzeigen will.
return None, None, "Bindungswurzel ist kein gültiger UTF-8-Pfad"
kandidat = Path(wert)
if not kandidat.is_absolute():
return None, None, "Bindungswurzel muss ein absoluter Pfad sein"
if ".." in kandidat.parts:
return None, None, "'..' ist in der Bindungswurzel verboten"
try:
aufgeloest = kandidat.resolve(strict=True)
except (OSError, ValueError) as exc:
return None, None, f"Bindungswurzel nicht lesbar — {exc}"
# Bewusst AUFLÖSEN statt kanonische Eingabe zu verlangen. Eine frühere
# Fassung lehnte jede nicht schon kanonische Wurzel ab; das machte den
# Tresor auf macOS unbrauchbar, weil dort /var selbst ein Symlink auf
# /private/var ist und das Betriebssystem Temporärpfade so ausliefert.
# Die Prüfung war zu streng für das, was sie schützen sollte.
#
# Die tragende Zusage ist nicht „die Eingabe war kanonisch", sondern „wir
# arbeiten auf einer vollständig aufgelösten Wurzel und folgen darunter
# nie einem Link": _walk_tree_no_links_within folgt keinem Alias, jedes
# Öffnen nutzt O_NOFOLLOW, und der (st_dev, st_ino)-Anker fällt auf, wenn
# jemand die Wurzel unter der Hand austauscht. Gebunden und gespeichert
# wird der aufgelöste Pfad, damit nichts still umgeleitet wird.
try:
status = os.lstat(str(aufgeloest))
except OSError as exc:
return None, None, f"Bindungswurzel nicht prüfbar — {exc}"
if not stat.S_ISDIR(status.st_mode):
return None, None, "Bindungswurzel ist kein Verzeichnis"
# Beidseitige Rückverweis-Sperre: ein Tresor bindet sich nie selbst, und
# eine Wurzel schließt den Tresor nie ein.
tresor = ROOT.resolve(strict=False)
if _resolved_within(tresor, aufgeloest) or _resolved_within(aufgeloest, tresor):
return None, None, (
"Bindungswurzel und Tresor dürfen einander nicht enthalten"
)
return aufgeloest, (status.st_dev, status.st_ino), None
def _lies_externes_dokument(wurzel, anker, relpfad):
"""Ein einzelnes externes Dokument eingesperrt lesen.
Rückgabe: ``(text, sha256, None)`` oder ``(None, None, grund)``.
"""
ziel, pfadfehler = _safe_relative_path(wurzel, relpfad)
if pfadfehler:
return None, None, pfadfehler
flags = (os.O_RDONLY | getattr(os, "O_BINARY", 0)
| getattr(os, "O_NOFOLLOW", 0) | getattr(os, "O_NONBLOCK", 0))
try:
fd = os.open(str(ziel), flags)
except OSError as exc:
return None, None, f"nicht lesbar — {exc}"
try:
status = os.fstat(fd)
# Nur echte Dateien. O_NONBLOCK verhindert, dass ein untergeschobenes
# FIFO den Prozess am Öffnen hängen lässt.
if not stat.S_ISREG(status.st_mode):
return None, None, "keine reguläre Datei"
if anker is not None and status.st_dev != anker[0]:
return None, None, (
"liegt auf einem anderen Dateisystem als die Bindungswurzel"
)
if status.st_size > MAX_EXTERN_BYTES_JE_DATEI:
return None, None, (
f"größer als {MAX_EXTERN_BYTES_JE_DATEI} Byte"
)
# st_nlink wird bewusst NICHT geprüft, anders als in
# _safe_regular_file: die Hardlink-Regel schützt die Portabilität des
# Artefakts. Auf einem rein lesenden Pfad, dessen Bytes nie
# manifestiert werden, schützt sie nichts.
with os.fdopen(fd, "rb", closefd=False) as f:
rohdaten = f.read(MAX_EXTERN_BYTES_JE_DATEI + 1)
except OSError as exc:
return None, None, f"nicht lesbar — {exc}"
finally:
os.close(fd)
if len(rohdaten) > MAX_EXTERN_BYTES_JE_DATEI:
return None, None, f"größer als {MAX_EXTERN_BYTES_JE_DATEI} Byte"
try:
text = rohdaten.decode("utf-8")
except UnicodeError as exc:
return None, None, f"kein gültiges UTF-8 — {exc}"
return text, _sha256_bytes(rohdaten), None
def _extern_dokumente(wurzel, anker):
"""Alle Markdown-Dokumente einer externen Wurzel deterministisch sammeln.
Rückgabe: ``(liste, None, None)`` oder ``(None, zustand, grund)``.
``zustand`` ist ``budget_exceeded``, wenn ein gezähltes Budget greift, und
``invalid_source``, wenn der Baum etwas enthält, das sich nicht
katalogisieren lässt — zwei Ursachen, zwei Zustände. Budgets werden
gezählt, nie über eine Uhr gestoppt; sonst wäre das Ergebnis nicht
reproduzierbar.
"""
try:
baum = _walk_tree_no_links_within(
wurzel, wurzel, max_tiefe=MAX_EXTERN_TIEFE,
max_eintraege=MAX_EXTERN_EINTRAEGE,
)
except BudgetUeberschritten as exc:
return None, "budget_exceeded", str(exc)
except OSError as exc:
return None, "invalid_source", str(exc)
ergebnis, gesamt = [], 0
for p in baum:
relpfad = _rel_zu(p, wurzel)
# Punkt-Verzeichnisse sind kein Wissen (.git und Konsorten).
if any(teil.startswith(".") for teil in Path(relpfad).parts):
continue
if p.suffix.lower() != ".md":
continue
if not _utf8_pfad(relpfad):
return None, "invalid_source", (
f"{relpfad!a}: Dateiname ist kein gültiges UTF-8")
if not _safe_regular_file_within(p, wurzel):
# Fail closed statt still überspringen: eine Datei, die wie ein
# Dokument heißt, aber keines ist (FIFO, Symlink, Gerätedatei),
# ist eine Auffälligkeit und kein Rauschen.
return None, "invalid_source", f"{relpfad}: keine reguläre Datei"
if len(ergebnis) >= MAX_EXTERN_DOKUMENTE:
return None, "budget_exceeded", (
f"mehr als {MAX_EXTERN_DOKUMENTE} Markdown-Dokumente")
text, digest, grund = _lies_externes_dokument(wurzel, anker, relpfad)
if grund:
return None, "invalid_source", f"{relpfad}: {grund}"
gesamt += len(text.encode("utf-8"))
if gesamt > MAX_EXTERN_BYTES_GESAMT:
return None, "budget_exceeded", (
f"mehr als {MAX_EXTERN_BYTES_GESAMT} Byte insgesamt")
ergebnis.append({"path": relpfad, "sha256": digest, "text": text})
return ergebnis, None, None
def _https_ziel(praefix, relpfad):
"""Vollständige URL unter dem registrierten Präfix bilden.
Der Katalogpfad ist ein Dateipfad, kein URL-Pfad: er wird kodiert. Ein
Leerzeichen oder Umlaut ließ die Anfrage sonst schon in http.client
scheitern; ein ``%`` im Dateinamen meint ein Prozentzeichen.
"""
from urllib.parse import quote
_, pfadfehler = _safe_relative_path(ROOT, relpfad)
if pfadfehler:
return None, pfadfehler
url = praefix.rstrip("/") + "/" + quote(relpfad, safe="/")
if not _unter_praefix(url, praefix):
return None, "Ziel liegt nicht unter dem registrierten Präfix"
return url, None
def _unter_praefix(url, praefix):
"""Ob ``url`` unter dem registrierten Präfix liegt — an Pfadgrenzen.
Ein reiner Zeichenkettenvergleich ließ ``https://beispiel.de.fremd.net/``
unter ``https://beispiel.de`` durchgehen und ``…/pfad-fremd/`` unter
``…/pfad``. Dazu kommen Punktsegmente: ``…/pfad/../anderswo`` beginnt mit
dem Präfix und zeigt doch hinaus — percent-kodiert genauso, und ein
kodierter Schrägstrich verschiebt die Segmentgrenze.
"""
from urllib.parse import unquote, urlsplit
if not isinstance(url, str) or not url.startswith("https://"):
return False
if "\\" in url or any(ord(z) < 33 or ord(z) == 127 for z in url):
return False
basis = praefix if praefix.endswith("/") else praefix + "/"
if not url.startswith(basis):
return False
for segment in urlsplit(url).path.split("/"):
klar = unquote(segment)
if klar in {".", ".."} or "/" in klar or "\\" in klar:
return False
if any(ord(z) < 32 or ord(z) == 127 for z in klar):
return False
return True
def _netz_oeffner(kontext):
"""Opener, der einer Weiterleitung NIE selbst folgt.
``urllib`` folgt 301/302/303/307/308 von sich aus. Die Präfixprüfung kam
dann erst nach dem Lesen, wenn das fremde Ziel die Anfrage längst gesehen
hatte. Hier endet jede Weiterleitung als HTTPError beim Aufrufer, und der
prüft das Ziel, bevor er die nächste Anfrage stellt.
"""
import urllib.request
class KeineWeiterleitung(urllib.request.HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
return urllib.request.build_opener(
KeineWeiterleitung(), urllib.request.HTTPSHandler(context=kontext))
def _netz_erlaubt():
"""Harte Offline-Schaltung. CI setzt sie, damit kein Test ins Netz kann."""
return os.environ.get(EXTERN_OFFLINE_ENV, "").strip() not in {"1", "true", "yes"}
def _hole_https(url, praefix, *, opener=None):
"""Ein Dokument unter dem registrierten Präfix abrufen.
Rückgabe: ``(bytes, None)`` oder ``(None, grund)``. Bewusst eng: nur https,
Zertifikatsprüfung zwingend, Redirects nur unterhalb desselben Präfix,
keine Auth-Header, keine Cookies. Ein Redirect, das das Präfix verlässt,
ist ein Abbruch und kein Umweg — und zwar BEVOR ihm gefolgt wird: Der
Opener folgt keiner Weiterleitung selbst (``_netz_oeffner``).
"""
import http.client
import ssl
import urllib.error
import urllib.request
from urllib.parse import urljoin
if not _netz_erlaubt():
return None, f"{EXTERN_OFFLINE_ENV} ist gesetzt — kein Netzzugriff"
if not _unter_praefix(url, praefix):
return None, "Ziel liegt nicht unter dem registrierten Präfix"
if opener is None:
oeffner = _netz_oeffner(ssl.create_default_context())
opener = oeffner.open
aktuell, gesehen = url, 0
while True:
anfrage = urllib.request.Request(
aktuell, method="GET",
headers={"User-Agent": f"SkillSafe/{ROOT.name} (wissenstresor)",
"Accept": "text/markdown, text/plain"},
)
try:
antwort = opener(anfrage, timeout=EXTERN_NETZ_TIMEOUT)
except urllib.error.HTTPError as exc:
ort = exc.headers.get("Location", "") if exc.headers else ""
try:
exc.close()
except Exception:
pass
if exc.code in (301, 302, 303, 307, 308):
gesehen += 1
if gesehen > EXTERN_NETZ_MAX_REDIRECTS:
return None, "zu viele Weiterleitungen"
# Relativ angegebene Ziele gegen die aktuelle URL auflösen,
# dann prüfen — die nächste Anfrage geht erst danach hinaus.
ziel = urljoin(aktuell, ort)
if not _unter_praefix(ziel, praefix):
return None, (
"Weiterleitung verlässt das registrierte Präfix"
)
aktuell = ziel
continue
return None, f"HTTP {exc.code}"
except (urllib.error.URLError, OSError, ValueError,
http.client.HTTPException) as exc:
return None, f"nicht erreichbar — {exc}"
# Ein Abruf kann auch NACH den Headern scheitern: die Verbindung
# reißt ab, das Zeitlimit greift beim Lesen, der Rumpf bleibt
# unvollständig. Das ist ein Abruffehler wie jeder andere — ein Grund
# für die Notizen, keine Ausnahme, die die Abfrage ohne JSON beendet.
try:
with antwort:
# Zweite Linie: folgt ein ersetzter Opener doch einer
# Weiterleitung, fällt das hier auf.
endgueltig = getattr(antwort, "url", aktuell) or aktuell
if not _unter_praefix(endgueltig, praefix):
return None, "Weiterleitung verlässt das registrierte Präfix"
rohdaten = antwort.read(MAX_EXTERN_BYTES_JE_DATEI + 1)
except (OSError, http.client.HTTPException) as exc:
return None, f"Abruf abgebrochen — {exc}"
if len(rohdaten) > MAX_EXTERN_BYTES_JE_DATEI:
return None, f"größer als {MAX_EXTERN_BYTES_JE_DATEI} Byte"
return rohdaten, None
def _katalog_score(dokument, query_norm, tokens):
"""Stufe 1: Katalogtext. Bewusst dieselben Gewichte wie die Seitenebene.
Der Katalogtext ist ein SCHWACHES Signal. Bei einer Netzquelle entscheidet
er, welche Dokumente überhaupt abgerufen werden; bei einer lokalen Quelle
nur die Reihenfolge des Lesens. Welches Dokument gewinnt, entscheidet er
nie.
"""
score = 0
titel = _retrieval_norm(dokument.get("title", ""))
if _phrase_present(titel, query_norm):
score += 80
titel_tokens = set(_retrieval_tokens(dokument.get("title", "")))
tag_tokens = set()
for tag in dokument.get("tags", []):
tag_tokens |= set(_retrieval_tokens(tag))
summary_tokens = set(_retrieval_tokens(dokument.get("summary", "")))
top_tokens = set()
for token in dokument.get("top_tokens", []):
top_tokens |= set(_retrieval_tokens(token))
for token in tokens:
if token in titel_tokens:
score += 30
if token in tag_tokens:
score += 24
if token in summary_tokens:
score += 12
if token in top_tokens:
score += 12
return score
def _bestand_score(text, query_norm, tokens):
"""Stufe 2: der tatsächliche Satzbestand. Das starke Signal.
Abgeglichen wird ausschließlich über ``_retrieval_tokens`` und
``_phrase_present`` — beide treffen nur an Tokengrenzen. Ein rohes ``in``
auf ungeteilten Strings gibt es hier nicht, sonst fände „himmel" ein
„schimmel". Der Fehler ist strukturell ausgeschlossen, nicht per
Konvention vermieden.
"""
saetze = _saetze(text)
getroffen, bester, beste_zahl = set(), None, -1
volltreffer, phrase = 0, False
for index, art, satz in saetze:
satz_tokens = set(_retrieval_tokens(satz))
treffer = satz_tokens & set(tokens)
getroffen |= treffer
if tokens and treffer == set(tokens):
volltreffer += 1
if _phrase_present(_retrieval_norm(satz), query_norm):
phrase = True
if len(treffer) > beste_zahl:
beste_zahl, bester = len(treffer), (index, art, satz)
abdeckung = (100 * len(getroffen) // len(tokens)) if tokens else 0
score = 4 * abdeckung + 40 * volltreffer + 20 * len(getroffen)
if phrase:
score += 80
return {"score": score, "coverage": abdeckung, "satz": bester,
"treffer": len(getroffen)}
def _extern_quelle_status(xid, zeile, bindung):
"""Bindungszustand einer aufgeführten Quelle bestimmen.
Netzquellen sind schon durch ihre Registrierung gebunden: ihre URL ist auf
jedem Host dieselbe. Lokale Quellen brauchen die maschinenlokale Bindung,
weil ein absoluter Pfad nichts über das Artefakt aussagt.
"""
if zeile.get("url"):
return {"modus": "netz", "wurzel": None, "anker": None,
"praefix": zeile["url"], "grund": None}
eintrag = bindung["bindings"].get(xid)
if not eintrag:
return {"modus": "unbound", "wurzel": None, "anker": None,
"praefix": None,
"grund": f"{xid} ist auf diesem Host nicht gebunden — "
f"'vault.py extern bind {xid} <pfad>'"}
wurzel, anker, grund = _resolve_external_root(eintrag.get("root"))
if grund:
return {"modus": "unbound", "wurzel": None, "anker": None,
"praefix": None, "grund": f"{xid}: {grund}"}
return {"modus": "lokal", "wurzel": wurzel, "anker": anker,
"praefix": None, "grund": None}
def _als_text(rohdaten):
"""Bytes eines externen Dokuments strikt als UTF-8 lesen.
Rückgabe: ``(text, sha256, None)`` oder ``(None, None, grund)``. Für den
frischen Abruf wie für den Cache dieselbe Regel: Vorher las der Cache mit
``errors="replace"``, und dieselben Bytes waren beim ersten Lauf
unlesbar, beim zweiten ein Treffer.
"""
try:
return rohdaten.decode("utf-8"), _sha256_bytes(rohdaten), None
except UnicodeError as exc:
return None, None, f"kein gültiges UTF-8 — {exc}"
def _protokoll_sperre():
"""Ob ein Netzabruf jetzt protokolliert werden könnte — sonst der Grund.
Geprüft VOR dem Socket: Ein Abruf, der nicht in ``log.md`` landen kann,
findet nicht statt. Hinterher ließe sich die Zusage „jeder Abruf steht im
Log" nicht mehr einlösen, nur noch melden.
"""
sicher, grund = _safe_output_target(LOG)
if not sicher:
return grund
if os.path.lexists(str(RELEASE_LOCK)):
return "Release-/Recovery-Lock vorhanden"
if not os.access(str(ROOT), os.W_OK):
return "der Skill-Ordner ist nicht beschreibbar"
if os.path.lexists(str(LOG)) and not os.access(str(LOG), os.W_OK):
return "log.md ist nicht beschreibbar"
return None
def _extern_dokument_text(status, relpfad, ttl, xid, protokoll, abrufe=None):
"""Ein externes Dokument JETZT lesen — Platte oder Netz.
„Live" heißt hier wörtlich: gerechnet wird gegen den Text, der in diesem
Moment dort steht, nie gegen den Katalog.
``abrufe`` ist das Abrufbudget der Abfrage (``{"rest": n}``) oder ``None``
für einen einzelnen Abruf ohne Budget. Ein Cache-Treffer verbraucht
nichts; ist das Budget vor einem echten Abruf aufgebraucht, kommt
``AbrufbudgetErschoepft`` — kein Lesefehler, sondern eine eigene Lücke.
"""
if status["modus"] == "lokal":
return _lies_externes_dokument(status["wurzel"], status["anker"], relpfad)
url, grund = _https_ziel(status["praefix"], relpfad)
if grund:
return None, None, grund
cache = _extern_cache_dir(xid) / (_sha256_bytes(url.encode("utf-8")) + ".md")
try:
if cache.is_file() and not cache.is_symlink():
alter = int(max(0.0, _jetzt() - cache.stat().st_mtime))
if ttl and alter <= ttl:
rohdaten = cache.read_bytes()
# Ausdrücklich markiert: ein Treffer jünger als eine Sekunde
# hat das Alter 0 und wurde früher als Abruf protokolliert.
protokoll.append({"url": url, "cache_age_seconds": alter,
"bytes": len(rohdaten), "aus_cache": True,
"sha256": _sha256_bytes(rohdaten)})
return _als_text(rohdaten)
except OSError:
pass
# Ab hier ginge eine Anfrage hinaus. Drei Bedingungen, alle vor dem
# ersten Socket: Netz erlaubt, Protokoll schreibbar, Budget übrig.
if not _netz_erlaubt():
return None, None, f"{EXTERN_OFFLINE_ENV} ist gesetzt — kein Netzzugriff"
sperre = _protokoll_sperre()
if sperre:
return None, None, (
f"nicht abgerufen — das Herkunftsprotokoll ist nicht schreibbar "
f"({sperre}), und ein Abruf ohne Protokolleintrag findet nicht statt"
)
if abrufe is not None:
if abrufe["rest"] <= 0:
raise AbrufbudgetErschoepft(
f"höchstens {EXTERN_NETZ_MAX_ABRUFE} Netzabrufe je Abfrage")
abrufe["rest"] -= 1
rohdaten, grund = _hole_https(url, status["praefix"])
if grund:
return None, None, grund
protokoll.append({"url": url, "cache_age_seconds": 0, "aus_cache": False,
"bytes": len(rohdaten), "sha256": _sha256_bytes(rohdaten)})
text, digest, grund = _als_text(rohdaten)
if grund:
# Abgerufen ist abgerufen: der Eintrag steht im Protokoll. In den
# Cache kommt nur, was sich auch lesen lässt.
return None, None, grund
try:
cache.parent.mkdir(parents=True, exist_ok=True)
cache.write_bytes(rohdaten)
except OSError:
pass
return text, digest, None
def _jetzt():
"""Wanduhr, gekapselt: sie kommt ausschließlich im Netzpfad vor."""
import time
return time.time()
def _lese_fremden_tresor(wurzel, anker):
"""Einen fremden SkillSafe als DATEN lesen. Sein Script läuft nie.
Wir rechnen sein MANIFEST.sha256 mit unserem eigenen ``sha256_file`` nach,
bevor wir irgendetwas glauben. Sein ``scripts/vault.py`` ist an dieser
Stelle eine Datei mit einer Prüfsumme — kein import, kein exec, kein
subprocess (AD-09, eiserne Regel 5). Gelesen wird danach ausschließlich,
was das Manifest pinnt, und nur in dem Stand, den es pinnt: Ein Dokument
unter ``knowledge/`` ohne Manifestzeile oder mit anderem Hash beim Lesen
bricht ab, statt als ungeprüfter Treffer durchzurutschen.
Rückgabe: ``(daten, None)`` oder ``(None, grund)``. Ein überschrittenes
gezähltes Budget ist kein Grund unter vielen, sondern eine eigene
Ausnahme (``BudgetUeberschritten``): der Aufrufer meldet es als
``budget_exceeded`` statt als ungültige Quelle.
"""
manifest, digest, grund = _lies_externes_dokument(
wurzel, anker, "MANIFEST.sha256")
if grund:
return None, f"MANIFEST.sha256 — {grund}"
geprueft = 0
# Was das Manifest pinnt, und mit welchem Hash. Gelesen wird nur, was
# hier steht — und nur in genau dem Stand, der hier steht.
soll_je_pfad = {}
for zeile in manifest.split("\n"):
if not zeile.strip():
continue
teile = zeile.split(maxsplit=1)
if len(teile) != 2 or not HASH_RE.fullmatch(teile[0]):
return None, "MANIFEST.sha256 ist nicht lesbar"
soll, relpfad = teile[0], teile[1].strip().lstrip("*")
ziel, pfadfehler = _safe_relative_path(wurzel, relpfad)
if pfadfehler:
return None, f"MANIFEST.sha256 nennt {relpfad!r} — {pfadfehler}"
try:
ist = sha256_file(ziel)
except OSError as exc:
return None, f"{relpfad} nicht prüfbar — {exc}"
if ist != soll:
return None, (
f"{relpfad}: Prüfsumme weicht vom fremden Manifest ab — "
f"der fremde Bestand ist nicht vertrauenswürdig"
)
soll_je_pfad[relpfad] = soll
geprueft += 1
if not geprueft:
return None, "MANIFEST.sha256 ist leer"
# Der Baumlauf darf scheitern, die Abfrage nicht: früher lief sein Fehler
# ungefangen durch und beendete sie mit einem Traceback statt mit genau
# einem JSON-Dokument.
try:
baum = _walk_tree_no_links_within(
wurzel / "knowledge", wurzel, max_tiefe=MAX_EXTERN_TIEFE,
max_eintraege=MAX_EXTERN_EINTRAEGE)
except BudgetUeberschritten:
raise
except OSError as exc:
return None, f"knowledge/ ist nicht lesbar — {exc}"
dokumente = []
for p in baum:
if p.suffix.lower() != ".md":
continue
relpfad = _rel_zu(p, wurzel)
if not _utf8_pfad(relpfad):
# Ein Dateiname aus Bytes ohne gültiges UTF-8 kommt als Surrogat
# an und brach später beim Hashen des Ergebnisses ab.
return None, f"{relpfad!a}: Dateiname ist kein gültiges UTF-8"
if not _safe_regular_file_within(p, wurzel):
# Fail closed statt still überspringen, wie beim Katalog-Gerüst:
# ein Symlink, ein Hardlink oder eine Sonderdatei, die wie ein
# Dokument heißt, ist im Skill-Artefakt verboten. Übersprungen
# sähe das Ergebnis vollständig aus, obwohl ein Dokument fehlt —
# ein Negativbefund über etwas, das nie gelesen wurde.
return None, (
f"{relpfad}: kein einfach verlinktes reguläres Dokument "
f"(Symlink, Hardlink oder Sonderdatei)"
)
soll = soll_je_pfad.get(relpfad)
if soll is None:
# Ein Dokument, das das fremde Manifest nicht pinnt, ist nie
# geprüft worden. Es zu lesen hieße, die Nachrechnung oben für
# genau das Material auszusetzen, das am Ende geliefert wird.
return None, (
f"{relpfad}: steht nicht im fremden Manifest — ungeprüftes "
f"Material wird nicht gelesen"
)
text, ist, grund = _lies_externes_dokument(wurzel, anker, relpfad)
if grund:
return None, f"{relpfad}: {grund}"
if ist != soll:
# Nachgerechnet wurde eben eine Datei; geliefert würden die Bytes
# dieses zweiten Lesens. Beides muss derselbe Stand sein.
return None, (
f"{relpfad}: hat sich seit der Manifestprüfung geändert — "
f"der fremde Bestand ist nicht vertrauenswürdig"
)
dokumente.append({"path": relpfad, "text": text})
return {"documents": dokumente, "manifest_sha256": digest,
"files": geprueft}, None
def build_external_result(snapshot, query, quellen_filter=None):
"""Externe Bezugsquellen zweistufig durchsuchen.
Ergebnisse landen NIE in ``evidence`` und nie im lokalen
``retrieval_fingerprint``: ein externer Satz ist ein Zeiger auf fremdes
Material, kein kuratierter Claim dieses Bestands.
Nur zwei Zustände sind Ergebnisse: ``external_candidates_found`` und
``no_external_candidates``. Beide setzen voraus, dass mindestens ein
Dokument tatsächlich gelesen wurde. Jeder andere Zustand heißt „es wurde
nichts gelesen" und ist ausdrücklich kein Negativbefund. Ein Block, der
nach „durchsucht und nichts gefunden" aussieht, obwohl kein Dokument
geöffnet wurde, ist derselbe Fehltreffer wie eine vertippte Quellen-ID —
und genauso teuer, weil er nicht als Fehler auffällt.
Seit ``extern-zweistufig/v2``: Eine lokale Quelle wird vollständig gelesen,
eine Netzquelle nur in den besten ``MAX_EXTERN_STUFE1`` Katalogeinträgen
und innerhalb von ``EXTERN_NETZ_MAX_ABRUFE`` Abrufen je Abfrage. Alles,
was dabei ungelesen bleibt, nennt der Grund.
"""
bindung, bindungsfehler = parse_bindung()
register = snapshot["extern"]["register"]
kataloge = snapshot["extern"]["orchestrators"]
query_norm = _retrieval_norm(query)
tokens = _anfragebegriffe(query)
block = {
# Die Vorbelegung ist bewusst KEIN Ergebniszustand: verlässt ein Pfad
# die Funktion, ohne den Zustand zu setzen, sieht das nie nach einem
# Negativbefund aus.
"state": "unreachable",
"algorithm": EXTERN_RETRIEVAL_PROFILE,
# 'live' wird verdient, nicht vorbelegt: wahr erst, wenn tatsächlich
# ein Dokument gelesen wurde und in dieses Ergebnis eingeht.
"live": False,
"fetched_at": None,
"sources": [],
"hits": [],
"reason": None,
"notes": list(bindungsfehler),
"external_fingerprint": None,
}
if not register:
block["state"] = "not_declared"
block["reason"] = (
f"{rel(EXTERN_REGISTER)} führt keine externe Bezugsquelle. "
f"Es wird ausschließlich aufgeführtes Material gelesen."
)
return block
# Eine nicht aufgeführte Quellen-ID still zu ignorieren wäre der
# gefährlichste Fehltreffer überhaupt: ein Tippfehler erzeugte dann einen
# glaubwürdig aussehenden Negativbefund („die Quelle wurde durchsucht und
# hat nichts hergegeben"). Deshalb fail closed, bevor gerankt wird.
unbekannt = sorted(set(quellen_filter or []) - set(register))
if unbekannt:
block["state"] = "invalid_query"
block["reason"] = (
f"Nicht aufgeführte Quelle(n) {unbekannt}. Es wurde nichts "
f"durchsucht — {EXTERN_KEIN_BEFUND}. Aufgeführt sind: "
f"{sorted(register)}."
)
return block
# Ohne einen suchbaren Begriff kann kein Dokument einen Treffer haben.
# Lesen und „nichts gefunden" melden hieße, einen Befund über eine Frage
# auszustellen, die gar nicht gestellt wurde.
if not tokens:
block["state"] = "invalid_query"
block["reason"] = (
f"Die Frage enthält keinen suchbaren Begriff (nur Stopp- und "
f"Funktionswörter oder Einzelzeichen). Es wurde nichts durchsucht "
f"— {EXTERN_KEIN_BEFUND}."
)
return block
treffer, wurzeln, protokoll, dokumentpfade = [], [], [], []
# Gezählte Grenzen der ganzen Abfrage: Netzabrufe über alle Netzquellen,
# gelesene Bytes über alle Quellen. Beides wird gezählt, nie über eine Uhr.
abrufe = {"rest": EXTERN_NETZ_MAX_ABRUFE}
gelesene_bytes = 0
netz_gelesen = 0
# Je berücksichtigter Quelle, aus der KEIN Dokument gelesen wurde, genau
# ein Eintrag (ursache, text). Die Ursache ist "not_bound" (lokale Quelle
# ohne brauchbare Bindung — Normalzustand eines frisch entpackten Pakets)
# oder "unreachable" (die Quelle hätte gelesen werden sollen, aber es kam
# kein Dokument an). Daraus entsteht unten der Zustand.
ungelesen = []
# Quellen, aus denen gelesen wurde, aber nicht alles Katalogisierte: ein
# Dokument war nicht lesbar, ein gezähltes Budget war erschöpft, oder
# Stufe 1 hat es bei einer Netzquelle gar nicht geöffnet. Auch das ist
# eine Lücke, und sie gehört in den Grund statt nur in die Notizen.
teilweise = []
# Fail closed ohne Teilergebnis: (zustand, grund), sobald ein fremder
# Tresor nicht vertrauenswürdig ist oder ein gezähltes Budget sprengt.
abbruch = None
def nicht_gelesen(ursache, text, notiz=True):
"""Eine Quelle ohne gelesenes Dokument festhalten — nie still."""
if notiz:
block["notes"].append(text)
ungelesen.append((ursache, text))
for xid in sorted(register):
zeile = register[xid]
if quellen_filter and xid not in quellen_filter:
continue
status = _extern_quelle_status(xid, zeile, bindung)
eintrag = _ohne_signatur({
"id": xid, "title": zeile["titel"], "kind": zeile["art"],
"scope": zeile["scope"], "trust": zeile["trust"],
"rights": zeile["rechte"], "target": zeile["ziel"],
"bound": status["modus"] != "unbound",
"mode": status["modus"],
}, ("title", "rights", "target"))
block["sources"].append(eintrag)
if status["modus"] == "unbound":
nicht_gelesen("not_bound", status["grund"])
continue
if status["modus"] == "netz" and not _netz_erlaubt():
eintrag["bound"] = False
nicht_gelesen(
"unreachable",
f"{xid}: {EXTERN_OFFLINE_ENV} ist gesetzt — nicht abgerufen",
)
continue
if zeile["art"] == "skillsafe-vault":
if status["modus"] != "lokal":
nicht_gelesen(
"unreachable",
f"{xid}: ein fremder Tresor wird nur lokal gelesen",
)
continue
try:
fremd, grund = _lese_fremden_tresor(
status["wurzel"], status["anker"])
except BudgetUeberschritten as exc:
abbruch = ("budget_exceeded", f"{xid}: {exc}")
break
if grund:
abbruch = ("invalid_external_source", f"{xid}: {grund}")
break
# Das Rezept des Fingerprints gehört zu extern-zweistufig/v1 und
# bleibt unverändert: jede Quelle, für die die Suche geöffnet
# wurde, geht mit ihrem Stand ein — auch wenn daraus am Ende kein
# Dokument kam. Lücken stehen im Grund, nicht im Fingerprint.
wurzeln.append([xid, fremd["manifest_sha256"]])
if not fremd["documents"]:
nicht_gelesen(
"unreachable",
f"{xid}: der fremde Tresor enthält kein Dokument unter "
f"knowledge/",
)
continue
for dok in fremd["documents"]:
dokumentpfade.append(f"{xid}:{dok['path']}")
bestand = _bestand_score(dok["text"], query_norm, tokens)
if bestand["treffer"] < EXTERN_MIN_BEGRIFFE or not bestand["satz"]:
continue
treffer.append(_extern_treffer(
xid, dok["path"], bestand, 0, zeile))
continue
katalog = kataloge.get(xid)
if not katalog:
nicht_gelesen(
"unreachable",
f"{xid}: kein Katalog sources/derived/{xid}__orchestrator.json "
f"— 'vault.py orchestrator-template {xid}' erzeugt das Gerüst",
)
continue
# Bei einer Netzquelle ist der Wurzel-Hash bewusst None; dann steht
# im Fingerprint "netz" und keine erfundene Zahl. Die Quelle geht ein,
# sobald die Suche für sie geöffnet wird — siehe oben beim fremden
# Tresor.
wurzeln.append([xid, katalog["meta"]["generated_from_sha256"] or "netz"])
ist_netz = status["modus"] == "netz"
reihenfolge = sorted(
((_katalog_score(dok, query_norm, tokens), dok["path"], dok)
for dok in katalog["documents"]),
key=lambda eintrag: (-eintrag[0], eintrag[1]),
)
# Stufe 1 filtert nur bei einer Netzquelle: dort ist jedes Öffnen ein
# Abruf, also teuer und nicht reproduzierbar. Lokal ist Lesen billig
# und deterministisch; dort ordnet der Katalog nur, und kein Dokument
# fällt einem schwachen Katalogtext zum Opfer.
vorauswahl = reihenfolge[:MAX_EXTERN_STUFE1] if ist_netz else reihenfolge
ungeoeffnet = len(reihenfolge) - len(vorauswahl)
ttl = bindung["cache_ttl_seconds"]
gelesen_hier = fehler_hier = budget_hier = 0
budget_gruende = []
for katalog_score, relpfad, dok in vorauswahl:
if gelesene_bytes >= MAX_EXTERN_BYTES_GESAMT:
budget_hier += 1
grund = f"höchstens {MAX_EXTERN_BYTES_GESAMT} Byte je Abfrage"
if grund not in budget_gruende:
budget_gruende.append(grund)
continue
try:
text, _, grund = _extern_dokument_text(
status, relpfad, ttl, xid, protokoll, abrufe)
except AbrufbudgetErschoepft as exc:
budget_hier += 1
if str(exc) not in budget_gruende:
budget_gruende.append(str(exc))
continue
if grund:
block["notes"].append(f"{xid}/{relpfad}: {grund}")
fehler_hier += 1
continue
gelesen_hier += 1
gelesene_bytes += len(text.encode("utf-8"))
if ist_netz:
netz_gelesen += 1
dokumentpfade.append(f"{xid}:{relpfad}")
bestand = _bestand_score(text, query_norm, tokens)
# Ohne einen einzigen Anfragebegriff fliegt das Dokument raus,
# egal wie gut der Katalogtext aussah. Genau hier wird er als
# schwaches Signal entwertet.
if bestand["treffer"] < EXTERN_MIN_BEGRIFFE or not bestand["satz"]:
continue
treffer.append(_extern_treffer(
xid, relpfad, bestand, katalog_score, zeile))
# Lücken dieser Quelle, je Ursache getrennt — der Grund nennt sie alle.
geoeffnet = gelesen_hier + fehler_hier
teile = []
if fehler_hier:
teile.append(
f"{fehler_hier} von {geoeffnet} geöffneten Dokumenten nicht lesbar")
if budget_hier:
text = (f"{budget_hier} Dokument(e) nicht geöffnet "
f"({'; '.join(budget_gruende)})")
teile.append(text)
block["notes"].append(f"{xid}: {text}")
if ungeoeffnet:
text = (f"{ungeoeffnet} von {len(reihenfolge)} katalogisierten "
f"Dokumenten nicht geöffnet (Stufe 1 öffnet bei einer "
f"Netzquelle höchstens {MAX_EXTERN_STUFE1})")
teile.append(text)
block["notes"].append(f"{xid}: {text}")
if not gelesen_hier:
if fehler_hier and not budget_hier and not ungeoeffnet:
# Die Einzelgründe stehen je Dokument schon in den Notizen.
text = (f"{xid}: kein Dokument lesbar ({geoeffnet} aus dem "
f"Katalog geöffnet)")
else:
text = f"{xid}: kein Dokument gelesen — {'; '.join(teile)}"
nicht_gelesen("unreachable", text, notiz=False)
continue
if teile:
teilweise.append(f"{xid}: {'; '.join(teile)}")
# Jeder Abruf steht im Log — auch dann, wenn die Suche gleich darauf
# fail-closed abbricht. Das Herkunftsprotokoll hängt nicht am Ergebnis.
protokoll_luecke = None
if protokoll:
alter = [e["cache_age_seconds"] for e in protokoll]
block["notes"].append(
f"{len(protokoll)} Abruf(e), Cache-Alter {min(alter)}–{max(alter)} s"
)
unprotokolliert = _log_abrufe(protokoll)
if unprotokolliert:
# Vor dem Abruf war log.md schreibbar, beim Eintragen nicht mehr.
# Ungeschehen machen lässt sich der Abruf nicht — gemeldet wird er.
protokoll_luecke = (
f"Herkunftsprotokoll unvollständig: {len(unprotokolliert)} "
f"Abruf(e) nicht in log.md eingetragen ({unprotokolliert[0]})"
)
block["notes"].append(protokoll_luecke)
def mit_protokollhinweis(grund):
if not protokoll_luecke:
return grund
return f"{grund} {protokoll_luecke}." if grund else f"{protokoll_luecke}."
if abbruch:
# Schon gelesene Dokumente anderer Quellen werden verworfen: ein
# Teilergebnis sähe aus wie ein vollständiges.
zustand, grund = abbruch
block["state"] = zustand
block["reason"] = mit_protokollhinweis(
f"{grund}. Die externe Suche wurde abgebrochen, es liegt kein "
f"Ergebnis vor — {EXTERN_KEIN_BEFUND}."
)
return block
gelesen = sorted(set(dokumentpfade))
# Alles Aufgeführte, das nicht gelesen wurde: ganze Quellen, einzelne
# nicht lesbare Dokumente, was ein gezähltes Budget abgeschnitten und was
# Stufe 1 bei einer Netzquelle nicht geöffnet hat. Fehlt dieser Zusatz im
# Grund, wurde jedes katalogisierte Dokument jeder berücksichtigten Quelle
# gelesen.
luecken = [text for _, text in ungelesen] + teilweise
offen = "; ".join(luecken)
if not gelesen:
# Kein Dokument gelesen heißt: es gibt kein Ergebnis. Der Zustand
# nennt die Ursache, bei gemischten Ursachen die schwerwiegendere —
# "unreachable" (etwas hätte lesbar sein sollen) vor "not_bound"
# (auf diesem Host bewusst nicht eingerichtet).
nur_ungebunden = bool(ungelesen) and all(
ursache == "not_bound" for ursache, _ in ungelesen)
block["state"] = "not_bound" if nur_ungebunden else "unreachable"
block["reason"] = (
f"Es wurde kein externes Dokument gelesen — {EXTERN_KEIN_BEFUND}. "
f"Nicht gelesen: {offen}."
)
if bindungsfehler:
block["reason"] += (
f" Die Bindungsdatei {rel(BINDUNG)} ist fehlerhaft "
f"(Einzelheiten in notes)."
)
block["reason"] = mit_protokollhinweis(block["reason"])
return block
block["live"] = True
# Der Abrufzeitpunkt gehört zu einem gelesenen Netzdokument. Ein Abruf,
# dessen Inhalt nicht lesbar war, steht im Protokoll, nicht hier.
if netz_gelesen:
block["fetched_at"] = date.today().isoformat()
treffer.sort(key=lambda t: (-t["score"], t["source_id"], t["document"],
t["sentence_index"]))
block["hits"] = treffer[:MAX_EXTERN_TREFFER]
if block["hits"]:
block["state"] = "external_candidates_found"
if luecken:
block["reason"] = (
f"Die Treffer stammen nur aus den gelesenen Dokumenten. "
f"Nicht gelesen: {offen}."
)
else:
block["state"] = "no_external_candidates"
ohne = sorted(set(tokens)) if tokens else []
# Die Aussage reicht genau so weit wie das Gelesene — nicht bis zu
# jedem aufgeführten Dokument.
block["reason"] = (
f"Kein gelesenes Dokument enthält die Anfragebegriffe {ohne} "
f"(gelesen: {len(gelesen)}). Fachbegriffe statt Eigennamen "
f"verwenden. Es wird bewusst kein bester Fehltreffer geliefert."
)
if luecken:
block["reason"] += (
f" Der Befund gilt nur für die gelesenen Dokumente. "
f"Nicht gelesen: {offen}."
)
block["reason"] = mit_protokollhinweis(block["reason"])
# Ein Fingerprint bezeugt ein Ergebnis. Ohne gelesenes Dokument gibt es
# keines; dort bleibt er null, statt einen Nicht-Befund zu bezeugen.
block["external_fingerprint"] = _sha256_bytes(json.dumps(
{"algorithm": EXTERN_RETRIEVAL_PROFILE,
"roots": sorted(wurzeln),
"query": query_norm,
"hits": [[t["source_id"], t["document"], t["sentence_index"],
t["score"]] for t in block["hits"]]},
ensure_ascii=False, sort_keys=True, separators=(",", ":"),
).encode("utf-8"))
block["documents_read"] = gelesen
return block
def _extern_treffer(xid, relpfad, bestand, katalog_score, zeile):
"""Einen externen Treffer bauen — immer als Zeiger, nie als Evidenz."""
index, art, satz = bestand["satz"]
verdaechtig = bool(PROMPT_INJECTION_RE.search(satz))
# Ein Dokumentpfad mit Signatur wird ausgegeben, denn er ist die Kennung
# des Treffers; der Treffer trägt dann das Signal.
pfad_verdaechtig = _pfad_mit_signatur(relpfad)
return {
"source_id": xid,
# Redundant an JEDEM Treffer: der Unterschied zu einem Claim darf
# sich nicht erst aus dem Kontext ergeben müssen.
"role": "external_pointer",
"is_evidence": False,
"document": relpfad,
"sentence_index": index,
"block": art,
# Ein Satz mit Instruktionssignatur wird gemeldet, nie ausgeliefert.
"text": None if verdaechtig else satz,
"text_sha256": _satz_digest(satz),
"score": int(bestand["score"]),
"score_catalog": int(katalog_score),
"score_inventory": int(bestand["score"]),
"coverage_percent": int(bestand["coverage"]),
"trust": zeile["trust"],
"signals": (["suspicious_instruction"]
if verdaechtig or pfad_verdaechtig else []),
}
def _log_abrufe(protokoll):
"""Herkunftsprotokoll: jeder Netzabruf ist in log.md nachlesbar.
Das ist der Unterschied zwischen „wie eine interne Quelle behandelt" und
„unbeaufsichtigt": wer prüfen will, ob nur aufgeführte Ziele gelesen
wurden, kann das nachlesen.
Läuft still: Die Abfrage schreibt genau ein JSON-Dokument auf stdout, und
eine Fehlerzeile von ``cmd_log`` davor machte es unlesbar. Was nicht
geschrieben werden konnte, kommt als Liste zurück und landet im Block.
"""
fehler = []
for eintrag in protokoll:
if eintrag.get("aus_cache"):
continue
ausgabe = io.StringIO()
try:
with contextlib.redirect_stdout(ausgabe):
ergebnis = cmd_log("extern", (
f"abruf {eintrag['url']} sha256={eintrag['sha256']} "
f"bytes={eintrag['bytes']}"
), still=True)
except Exception as exc: # auch RollbackIncompleteError: nie ohne JSON
ergebnis = 1
ausgabe.write(f"{type(exc).__name__}: {exc}")
if ergebnis != 0:
zeilen = [z.strip() for z in ausgabe.getvalue().splitlines()
if z.strip()]
meldung = zeilen[-1] if zeilen else "log.md nicht beschreibbar"
meldung = re.sub(r"^\W*log:\s*", "", meldung)
fehler.append(f"{eintrag['url']} — {meldung}")
return fehler
def _tracked_path(p: Path) -> bool:
"""Ob ein Tresorpfad Bestandteil des Integritätsmanifests ist."""
rp = Path(rel(p))
teile = rp.parts
if not teile:
return False
# .vault-extern.json ist wie log.md bewusst außerhalb des Manifests: sie
# enthält absolute Pfade dieses Hosts. Stünde sie im Manifest, wäre das
# Artefakt nicht mehr portabel und die Paket-SHA-256 maschinenabhängig.
if p in {MANIFEST, LOG, RELEASE_LOCK, BINDUNG}:
return False
if "__pycache__" in teile or p.suffix == ".pyc" or teile[0] == "evals":
return False
if teile[:2] == ("sources", "quarantine"):
return p == QUARANTINE / "README.md"
return True
def _open_parent_dir_fd(ziel: Path):
"""Elternordner komponentenweise und ohne Link-Folgen verankern."""
if os.open not in os.supports_dir_fd or os.rename not in os.supports_dir_fd:
raise OSError(
"sichere dir_fd-Dateiersetzung wird auf dieser Plattform nicht unterstützt"
)
try:
teile = ziel.parent.relative_to(ROOT).parts
except ValueError as exc:
raise OSError("Schreibziel liegt außerhalb des Tresors") from exc
flags = (os.O_RDONLY | getattr(os, "O_DIRECTORY", 0)
| getattr(os, "O_NOFOLLOW", 0) | getattr(os, "O_CLOEXEC", 0))
fd = os.open(str(ROOT), flags)
try:
for teil in teile:
naechster = os.open(teil, flags, dir_fd=fd)
os.close(fd)
fd = naechster
return fd
except BaseException:
os.close(fd)
raise
def _assert_parent_fd(fd, ordner: Path):
"""Prüfen, dass der gehaltene Verzeichnis-FD noch zum Tresorpfad gehört."""
if _first_symlink_component(ordner) is not None:
raise OSError(f"{rel(ordner)}: Elternpfad wurde durch einen Link ersetzt")
gehalten = os.fstat(fd)
aktuell = os.lstat(str(ordner))
if (gehalten.st_dev, gehalten.st_ino) != (aktuell.st_dev, aktuell.st_ino):
raise OSError(f"{rel(ordner)}: Elternverzeichnis wurde während des Schreibens ersetzt")
def _read_regular_at(fd, name, fehlt_erlaubt=False, mit_modus=False):
flags = os.O_RDONLY | getattr(os, "O_BINARY", 0) | getattr(os, "O_NOFOLLOW", 0)
try:
datei_fd = os.open(name, flags, dir_fd=fd)
except FileNotFoundError:
if fehlt_erlaubt:
return None
raise
try:
status = os.fstat(datei_fd)
if not stat.S_ISREG(status.st_mode) or status.st_nlink != 1:
raise OSError(f"{name}: Ziel ist keine einfach verlinkte reguläre Datei")
teile = []
while True:
chunk = os.read(datei_fd, 65536)
if not chunk:
break
teile.append(chunk)
daten = b"".join(teile)
if mit_modus:
return daten, stat.S_IMODE(status.st_mode)
return daten
finally:
os.close(datei_fd)
def _replace_files_transactionally(outputs, precommit=None, postcheck=None):
"""Mehrere kleine Release-Dateien vorbereiten, ersetzen und ggf. zurückrollen.
``outputs`` behält seine Einfügereihenfolge; das Manifest wird vom
Release bewusst zuletzt übergeben und dient damit als Commit-Marker.
"""
if not outputs:
return
originals, parent_fds = {}, {}
try:
for ziel, daten in outputs.items():
sicher, grund = _safe_output_target(ziel)
if not sicher:
raise OSError(f"{rel(ziel)}: unsicheres Schreibziel — {grund}")
if not isinstance(daten, bytes):
raise TypeError(f"{rel(ziel)}: Transaktionsinhalt muss bytes sein")
if ziel.parent not in parent_fds:
parent_fds[ziel.parent] = _open_parent_dir_fd(ziel)
parent_fd = parent_fds[ziel.parent]
_assert_parent_fd(parent_fd, ziel.parent)
originals[ziel] = _read_regular_at(
parent_fd, ziel.name, fehlt_erlaubt=True, mit_modus=True
)
with tempfile.TemporaryDirectory(prefix=f".{ROOT.name}-release-",
dir=str(ROOT.parent)) as tmp:
tmpdir = Path(tmp)
staged = {}
for n, (ziel, daten) in enumerate(outputs.items()):
stage = tmpdir / f"{n:02d}.stage"
with open(stage, "wb") as f:
vorher = originals[ziel]
os.fchmod(f.fileno(), vorher[1] if vorher is not None else 0o600)
f.write(daten)
f.flush()
os.fsync(f.fileno())
staged[ziel] = stage
if precommit is not None:
precommit()
committed = []
try:
for ziel in outputs:
parent_fd = parent_fds[ziel.parent]
_assert_parent_fd(parent_fd, ziel.parent)
# Vor dem Replace vormerken: Auch eine Unterbrechung direkt
# nach erfolgreichem Replace wird so zurückgerollt.
committed.append(ziel)
os.replace(
str(staged[ziel]), ziel.name, dst_dir_fd=parent_fd
)
os.fsync(parent_fd)
for ziel, daten in outputs.items():
parent_fd = parent_fds[ziel.parent]
_assert_parent_fd(parent_fd, ziel.parent)
if _read_regular_at(parent_fd, ziel.name) != daten:
raise OSError(
f"{rel(ziel)}: Nachprüfung nach Replace fehlgeschlagen"
)
if postcheck is not None:
postcheck()
for ziel, daten in outputs.items():
parent_fd = parent_fds[ziel.parent]
_assert_parent_fd(parent_fd, ziel.parent)
if _read_regular_at(parent_fd, ziel.name) != daten:
raise OSError(
f"{rel(ziel)}: Nachprüfung nach Endkontrolle fehlgeschlagen"
)
except BaseException as commit_fehler:
rollback_fehler = []
for n, ziel in enumerate(reversed(committed)):
parent_fd = parent_fds[ziel.parent]
try:
alt = originals[ziel]
if alt is None:
try:
os.unlink(ziel.name, dir_fd=parent_fd)
except FileNotFoundError:
pass
else:
alt_daten, alt_modus = alt
rollback = tmpdir / f"rollback-{n:02d}.stage"
with open(rollback, "wb") as f:
os.fchmod(f.fileno(), alt_modus)
f.write(alt_daten)
f.flush()
os.fsync(f.fileno())
os.replace(
str(rollback), ziel.name, dst_dir_fd=parent_fd
)
os.fsync(parent_fd)
except Exception as exc:
rollback_fehler.append(f"{rel(ziel)}: {exc}")
for ordner, parent_fd in parent_fds.items():
try:
_assert_parent_fd(parent_fd, ordner)
except Exception as exc:
rollback_fehler.append(f"{rel(ordner)}: {exc}")
if rollback_fehler:
raise RollbackIncompleteError(
f"Commit fehlgeschlagen ({commit_fehler}); "
f"Rollback unvollständig: " + "; ".join(rollback_fehler)
) from commit_fehler
raise
finally:
for fd in parent_fds.values():
try:
os.close(fd)
except OSError:
pass
def _acquire_release_lock():
try:
fd = os.open(str(RELEASE_LOCK), os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
except FileExistsError as exc:
raise OSError(
f"{rel(RELEASE_LOCK)} existiert — anderer oder abgebrochener Release; "
f"Zustand prüfen, Lock danach bewusst entfernen"
) from exc
try:
os.write(fd, f"pid={os.getpid()}\n".encode("ascii"))
os.fsync(fd)
except Exception:
try:
_release_lock_freigeben(fd)
except OSError:
pass
raise
return fd
def _release_lock_freigeben(fd):
gehalten = os.fstat(fd)
try:
aktuell = os.lstat(str(RELEASE_LOCK))
except OSError:
os.close(fd)
raise OSError("Release-Lockpfad fehlt vor der Freigabe")
if (gehalten.st_dev, gehalten.st_ino) != (aktuell.st_dev, aktuell.st_ino):
os.close(fd)
raise OSError("Release-Lock wurde ausgetauscht; fremden Lock nicht entfernt")
os.unlink(str(RELEASE_LOCK))
os.close(fd)
def _release_lock_behalten(fd, grund):
"""Recovery-Hinweis in den Lock schreiben und den Pfad bewusst behalten."""
hinweis = re.sub(r"[\r\n\x00-\x1f\x7f]+", " ", str(grund)).strip()
os.lseek(fd, 0, os.SEEK_END)
os.write(fd, f"recovery_required={hinweis}\n".encode("utf-8"))
os.fsync(fd)
os.close(fd)
def _run_locked_mutation(name, operation):
"""Alle schreibenden Einzelkommandos mit demselben Lock serialisieren."""
try:
fd = _acquire_release_lock()
except OSError as exc:
print(f"🔴 {name}: Schreib-Lock nicht verfügbar — {exc}")
return 1
ergebnis, recovery = 1, None
try:
ergebnis = operation()
except RollbackIncompleteError as exc:
recovery = exc
print(f"🔴 {name}: KRITISCH — Rollback unvollständig: {exc}")
finally:
try:
if recovery is not None:
_release_lock_behalten(fd, recovery)
else:
_release_lock_freigeben(fd)
except OSError as exc:
print(f"🔴 {name}: Lock konnte nicht sicher abgeschlossen werden — {exc}")
ergebnis = 1
return ergebnis
def _release_input_fingerprint():
"""Snapshot aller Release-Eingaben; abgeleitete Dateien bleiben außen vor."""
ignorieren = {INDEX, GRAPH}
h = hashlib.sha256()
eingaben = [p for p in _tracked_files() if p not in ignorieren]
if LOG.is_file() and not LOG.is_symlink():
eingaben.append(LOG)
for p in sorted(eingaben, key=lambda x: rel(x)):
h.update(rel(p).encode("utf-8"))
h.update(b"\0")
h.update(sha256_file(p).encode("ascii"))
h.update(b"\n")
return h.hexdigest()
def _checksum_entries(overrides=None):
"""Prüfsummen des aktuellen oder eines vorbereiteten Endstands."""
overrides = overrides or {}
pfade = set(_tracked_files())
for p in overrides:
if _tracked_path(p):
pfade.add(p)
eintraege = {}
for p in sorted(pfade, key=lambda x: rel(x)):
if p in overrides:
eintraege[rel(p)] = _sha256_bytes(overrides[p])
else:
eintraege[rel(p)] = sha256_file(p)
return eintraege
def _manifest_bytes(overrides=None):
eintraege = _checksum_entries(overrides=overrides)
text = "".join(f"{h} {rp}\n" for rp, h in sorted(eintraege.items()))
return text.encode("utf-8"), len(eintraege)
def _tracked_files():
# log.md ist bewusst NICHT im Manifest: das Journal wächst append-only
# weiter (auch der Release-Eintrag selbst) und würde jedes Manifest
# sofort wieder invalidieren. Historie ist Nachweis, nicht Inhalt.
# evals/ (nur auf oberster Ebene) ist ebenfalls ausgenommen: Werkstatt-
# material des Skill-Creators, das beim Packaging nicht mitgeliefert
# wird — stünde es im Manifest, schlüge verify nach Installation fehl.
ergebnis = []
for p in _walk_tree_no_links(ROOT):
if _is_path_alias(p):
raise ValueError(f"{rel(p)}: Symlink/Reparse-Point im Tresor verboten")
status = os.lstat(str(p))
if stat.S_ISDIR(status.st_mode):
continue
if not stat.S_ISREG(status.st_mode):
raise ValueError(f"{rel(p)}: nur reguläre Dateien/Ordner sind erlaubt")
if status.st_nlink != 1:
raise ValueError(f"{rel(p)}: mehrfach hart verlinkte Datei ist verboten")
if not _tracked_path(p):
continue
rp = rel(p)
kanonisch, pfadfehler = _safe_relative_path(ROOT, rp)
if pfadfehler or kanonisch != p:
raise ValueError(f"{rp!r}: nicht als portabler Manifestpfad darstellbar")
ergebnis.append(p)
return ergebnis
def _manifest_status():
"""Manifest ohne Ausgabe gegen den aktuellen Bestand prüfen."""
try:
aktuell = _checksum_entries()
except (OSError, RuntimeError, ValueError) as exc:
return [f"MANIFEST: aktueller Bestand kann nicht sicher gelesen werden — {exc}"], 0
if not _safe_regular_file(MANIFEST):
return ["MANIFEST.sha256 fehlt oder ist keine sichere reguläre Datei"], 0
try:
manifest_text = read(MANIFEST)
except (OSError, UnicodeError) as exc:
return [f"MANIFEST.sha256 ist nicht als UTF-8 lesbar — {exc}"], 0
soll, manifest_fehler = {}, []
for n, line in enumerate(manifest_text.split("\n"), 1):
if not line.strip():
continue
m = re.match(r"^([0-9a-f]{64}) (\S.*)$", line)
if not m:
manifest_fehler.append(
f"MANIFEST Zeile {n}: erwartet '<sha256> <relativer-pfad>'"
)
continue
h, rp = m.groups()
pfad, pfadfehler = _safe_relative_path(ROOT, rp)
if (pfadfehler or rel(pfad) != rp or not _tracked_path(pfad)):
manifest_fehler.append(f"MANIFEST Zeile {n}: Pfad {rp!r} unzulässig")
continue
if rp in soll:
manifest_fehler.append(f"MANIFEST Zeile {n}: Pfad {rp!r} doppelt")
continue
soll[rp] = h
if manifest_fehler:
return manifest_fehler, len(soll)
neu = sorted(set(aktuell) - set(soll))
weg = sorted(set(soll) - set(aktuell))
anders = sorted(rp for rp in set(soll) & set(aktuell) if soll[rp] != aktuell[rp])
probleme = (
[f"NEU {rp}" for rp in neu]
+ [f"FEHLT {rp}" for rp in weg]
+ [f"GEÄNDERT {rp}" for rp in anders]
)
return probleme, len(soll)
def cmd_checksum(verify=False):
if _quarantine_payloads():
print("🔴 checksum: Quarantäne nicht leer — ungeprüfte Inhalte verhindern "
"ein Integritätsmanifest.")
return 1
if verify:
probleme, anzahl = _manifest_status()
for problem in probleme:
symbol = "🟡" if problem.startswith("NEU ") else "🔴"
print(f"{symbol} {problem}")
if probleme:
print(f"\nverify: {len(probleme)} Abweichungen/Fehler — "
f"Stand entspricht NICHT dem Manifest.")
return 1
print(f"🟢 verify: {anzahl} Dateien unverändert — Stand = Manifest.")
return 0
def arbeit():
if _quarantine_payloads():
print("🔴 checksum: Quarantäne wurde während des Schreibens befüllt.")
return 1
try:
inhalt, anzahl = _manifest_bytes()
def endkontrolle():
probleme, _ = _manifest_status()
if probleme:
raise RuntimeError(
"geschriebenes Manifest ist nicht selbstkonsistent: "
+ "; ".join(probleme)
)
_replace_files_transactionally(
{MANIFEST: inhalt}, postcheck=endkontrolle
)
except RollbackIncompleteError:
raise
except (OSError, RuntimeError, TypeError, ValueError) as exc:
print(f"🔴 checksum: Schreiben fehlgeschlagen — {exc}")
return 1
print(f"🟢 checksum: {rel(MANIFEST)} geschrieben ({anzahl} Dateien). "
f"Jede inhaltliche Änderung invalidiert dieses Manifest.")
return 0
return _run_locked_mutation("checksum", arbeit)
def cmd_log(aktion, text, still=False):
if aktion not in LOG_AKTIONEN:
print(f"🔴 log: Aktion muss eine sein von {sorted(LOG_AKTIONEN)}")
return 1
if any(ord(zeichen) < 32 or ord(zeichen) == 127 for zeichen in text):
print("🔴 log: Steuerzeichen und Zeilenumbrüche im Logtext sind verboten")
return 1
def arbeit():
sicher, grund = _safe_output_target(LOG)
if not sicher:
print(f"🔴 log: unsicheres Schreibziel — {grund}")
return 1
eintrag = f"## [{date.today().isoformat()}] {aktion} | {text}"
bisher = read(LOG) if LOG.exists() else ""
if bisher and not bisher.endswith("\n"):
bisher += "\n"
try:
_replace_files_transactionally(
{LOG: (bisher + eintrag + "\n").encode("utf-8")}
)
except RollbackIncompleteError:
raise
except (OSError, RuntimeError, TypeError) as exc:
print(f"🔴 log: Schreiben fehlgeschlagen — {exc}")
return 1
if not still:
print(f"🟢 log: angehängt — {eintrag}")
return 0
return _run_locked_mutation("log", arbeit)
def cmd_stats():
(fehler, warn, seiten, claims, register, _,
extern_kontext) = cmd_validate(still=True)
worlds, concepts, _ = parse_concepts()
media, _ = parse_media_representations(register)
g = build_graph(seiten)
dom, typ, status, tiers = {}, {}, {}, {}
for s in seiten.values():
fm = s["fm"]
dom[fm.get("domain", "?")] = dom.get(fm.get("domain", "?"), 0) + 1
typ[fm.get("type", "?")] = typ.get(fm.get("type", "?"), 0) + 1
status[fm.get("status", "?")] = status.get(fm.get("status", "?"), 0) + 1
tier = _trust_tier(fm.get("geprueft_von"))
tiers[tier] = tiers.get(tier, 0) + 1
print(f"Profil {PROFIL} — {len(seiten)} Seiten, {len(claims)} Claims, "
f"{len(register)} Quellen, {len(g['kanten'])} Kanten "
f"({len(fehler)} Fehler, {len(warn)} Warnungen)")
print(f" Begriffswelten: {len(worlds)}, Begriffe: {len(concepts)}, "
f"Medienrepräsentationen: {len(media)}")
# Bewusst eine eigene Zeile: die Kopfzeile oben ist das Muster, das
# tools/check_docs.py liest. Ein zusätzliches Feld darin würde den
# Zahlenwächter an der eigenen Erweiterung brechen.
anker = sum(len(eintrag["anchors"])
for eintrag in extern_kontext["anchors"].values())
print(f" Externe Bezugsquellen: {len(extern_kontext['register'])}, "
f"Satzanker: {anker}, "
f"Kataloge: {len(extern_kontext['orchestrators'])}")
# Was die Zusage "nichts übersehen" kostet, als Zahl statt als Gefühl:
# so viele Stapel liest das Modell bei einer Vollsichtung.
stapel = _sweep_stapel(
sorted((pfad, s["claims"]) for pfad, s in seiten.items()
if s["claims"]),
SWEEP_STANDARD_GROESSE,
)
print(f" Vollsichtung: {len(claims)} Claims, Stapel: {len(stapel)}, "
f"Stapelgröße: {SWEEP_STANDARD_GROESSE}")
for name, d in (("Domänen", dom), ("Typen", typ), ("Status", status),
("Trust-Tiers", tiers)):
print(f" {name}: " + ", ".join(f"{k}={v}" for k, v in sorted(d.items())))
return 0
def cmd_source(pfad):
p = Path(pfad)
if _is_path_alias(p) or not p.is_file():
print(f"🔴 source: {pfad} nicht gefunden oder ist ein Symlink/Reparse-Point")
return 1
register, _ = parse_register()
naechste = max([int(s[2:]) for s in register] or [0]) + 1
sid = f"S-{naechste:04d}"
try:
h = sha256_file(p)
except OSError as exc:
print(f"🔴 source: Datei kann nicht sicher gehasht werden — {exc}")
return 1
print(f"Datei : {p.name} ({p.stat().st_size} Bytes)")
print(f"SHA-256 : {h}")
print(f"Nächste ID: {sid}")
print("Registerzeile (Titel/Stand/Trust/Rechte ausfüllen, Datei nach sources/raw/ verschieben):")
print(f"| {sid} | TITEL | JJJJ-MM-TT | {h} | T? | RECHTE | sources/raw/{sid}__{p.name} |")
return 0
UMLAUT = str.maketrans({"ä": "ae", "ö": "oe", "ü": "ue",
"Ä": "ae", "Ö": "oe", "Ü": "ue", "ß": "ss"})
def _norm(s):
return re.sub(r"\s+", " ", s.lower().translate(UMLAUT)).strip()
def cmd_route(frage_woerter):
"""Deterministisches Routing: Frage → Domäne(n) → Seiten.
Kein Modell, keine Wahrscheinlichkeit — Schlagwort-Abgleich gegen
ROUTER.md (Mehrwort-Schlagworte als Teilstring der normalisierten
Frage). Treffer in mehreren Domänen ⇒ Mischfrage wird gemeldet und
pro Domäne getrennt beantwortet. Das Ergebnis ist ein nachvollzieh-
barer VORSCHLAG; die finale Einordnung trifft das Modell anhand von
INDEX.md und benennt es, wenn es den Router überstimmt.
"""
fehler, _, _, _, _, router, _ = cmd_validate(still=True)
if fehler:
for f in fehler:
print(f"🔴 {f}")
print("🔴 route: Tresor ist nicht valide — Routing fail-closed abgebrochen.")
return 1
frage = _norm(" ".join(frage_woerter))
treffer = {}
for dom in sorted(router):
worte = sorted({w for w in router[dom]["schlagworte"]
if _norm(w) and _norm(w) in frage})
if worte:
treffer[dom] = worte
if not treffer:
print("route: kein Schlagwort-Treffer.")
print("Weiter mit: python3 scripts/vault.py query \"<frage>\" — "
"der Router ist nur ein Hinweis. Die Abfrage sagt, wie viel "
"der Frage sie erkannt hat, und ob die Vollsichtung (sweep) "
"Pflicht ist. 'search' hilft mit Synonymen, ist aber kein "
"Negativbeweis.")
return 1
if len(treffer) > 1:
print(f"🟡 MISCHFRAGE — berührt {len(treffer)} Domänen "
f"({', '.join(sorted(treffer))}): pro Domäne getrennt "
f"beantworten, Quellen nicht vermischen.")
for dom in sorted(treffer):
print(f"route: Domäne {dom} (Schlagworte: {', '.join(treffer[dom])})")
for seite in router[dom]["seiten"]:
print(f" → {seite}")
print("Hinweis: Vorschlag, kein Urteil — finale Auswahl über INDEX.md; "
"Überstimmen des Routers in der Antwort benennen.")
return 0
def cmd_release(stufe):
"""Transaktionale Release-Kette mit Gate, Lock und Rollback.
Alle Ergebnisse werden erst im Speicher und in temporären Dateien
vorbereitet. Danach werden Index, Graph, VERSION und Log ersetzt;
das Manifest kommt als Commit-Marker zuletzt. Jeder behandelte
Schreibfehler stellt den vorherigen Byte-Stand vollständig wieder her.
"""
if stufe not in ("major", "minor", "patch"):
print("🔴 release: Stufe muss major|minor|patch sein")
return 1
lock_fd, committed, lock_behalten = None, False, False
ergebnis, status = 1, None
try:
lock_fd = _acquire_release_lock()
fingerprint = _release_input_fingerprint()
(fehler, warnungen, seiten, claims, register, _,
_) = cmd_validate(still=True)
if fehler:
for f in fehler:
print(f"🔴 {f}")
raise RuntimeError("validate schlägt fehl (fail-closed)")
if _release_input_fingerprint() != fingerprint:
raise RuntimeError("Eingabestand hat sich während der Validierung verändert")
if not _safe_regular_file(VERSION):
raise ValueError("VERSION fehlt oder ist keine sichere reguläre Datei")
alt = read(VERSION).strip()
if not VERSION_RE.fullmatch(alt):
raise ValueError(f"VERSION '{alt}' ist kein SemVer x.y.z")
ma, mi, pa = (int(x) for x in alt.split("."))
ma, mi, pa = {"major": (ma + 1, 0, 0),
"minor": (ma, mi + 1, 0),
"patch": (ma, mi, pa + 1)}[stufe]
neu = f"{ma}.{mi}.{pa}"
if LOG.exists() and not _safe_regular_file(LOG):
raise OSError("log.md ist kein sicheres reguläres Schreibziel")
index_bytes = build_index(seiten).encode("utf-8")
graph = build_graph(seiten)
graph_bytes = (json.dumps(graph, ensure_ascii=False, indent=2,
sort_keys=True) + "\n").encode("utf-8")
version_bytes = (neu + "\n").encode("utf-8")
bisheriges_log = read(LOG) if LOG.exists() else ""
if bisheriges_log and not bisheriges_log.endswith("\n"):
bisheriges_log += "\n"
log_eintrag = (
f"## [{date.today().isoformat()}] release | v{neu} — "
f"{len(seiten)} Seiten, {len(claims)} Claims, "
f"{len(register)} Quellen ({stufe})\n"
)
log_bytes = (bisheriges_log + log_eintrag).encode("utf-8")
vorbereitet = {
INDEX: index_bytes,
GRAPH: graph_bytes,
VERSION: version_bytes,
LOG: log_bytes,
}
manifest_bytes, manifest_anzahl = _manifest_bytes(overrides=vorbereitet)
vorbereitet[MANIFEST] = manifest_bytes # Commit-Marker bewusst zuletzt.
if _quarantine_payloads():
raise RuntimeError("Quarantäne wurde während des Release befüllt")
if _release_input_fingerprint() != fingerprint:
raise RuntimeError("Eingabestand hat sich während des Release verändert")
def precommit():
if _quarantine_payloads():
raise RuntimeError("Quarantäne wurde vor dem Commit befüllt")
if _release_input_fingerprint() != fingerprint:
raise RuntimeError("Eingabestand hat sich vor dem Commit verändert")
def endkontrolle():
endfehler, _, endseiten, _, _, _, _ = cmd_validate(still=True)
if endfehler:
raise RuntimeError(
"Endzustand verletzt validate: " + "; ".join(endfehler)
)
if read(INDEX) != build_index(endseiten):
raise RuntimeError("INDEX.md ist im Endzustand inkonsistent")
graph_soll = (
json.dumps(build_graph(endseiten), ensure_ascii=False,
indent=2, sort_keys=True) + "\n"
)
if read(GRAPH) != graph_soll:
raise RuntimeError("graph/graph.json ist im Endzustand inkonsistent")
manifest_fehler, _ = _manifest_status()
if manifest_fehler:
raise RuntimeError(
"Endmanifest ist inkonsistent: " + "; ".join(manifest_fehler)
)
_replace_files_transactionally(
vorbereitet, precommit=precommit, postcheck=endkontrolle
)
committed = True
ergebnis = 0
status = (neu, warnungen, len(seiten), len(graph["knoten"]),
len(graph["kanten"]), manifest_anzahl)
except RollbackIncompleteError as exc:
lock_behalten = True
print(f"🔴 release: KRITISCH — Rollback unvollständig: {exc}. "
f"Recovery-Lock bleibt bestehen; nicht veröffentlichen.")
except (OSError, RuntimeError, TypeError, ValueError) as exc:
print(f"🔴 release: ABBRUCH — {exc}. "
f"Release-Ziele wurden nicht veröffentlicht oder zurückgerollt.")
finally:
if lock_fd is not None:
try:
if lock_behalten:
_release_lock_behalten(lock_fd, "Rollback unvollständig")
else:
_release_lock_freigeben(lock_fd)
except OSError as exc:
if committed:
print(f"🔴 release: Inhalt committed, aber Lock-Abschluss unsicher — {exc}")
else:
print(f"🔴 release: Lock konnte nicht sicher abgeschlossen werden — {exc}")
ergebnis = 1
if committed and ergebnis == 0:
neu, warnungen, seiten_anzahl, knoten, kanten, manifest_anzahl = status
try:
print(f"🟢 index: {seiten_anzahl} Seiten vorbereitet.")
print(f"🟢 graph: {knoten} Knoten, {kanten} Kanten vorbereitet.")
print(f"🟢 checksum: {manifest_anzahl} Dateien im Endstand gepinnt.")
if warnungen:
print(f"🟡 release: v{neu} mit {len(warnungen)} Warnungen "
f"(Details: vault.py doctor).")
else:
print(f"🟢 release: v{neu} transaktional veröffentlicht.")
except OSError:
# Ausgabeproblem ändert den bereits verifizierten Commit nicht.
pass
return ergebnis
# --------------------------------------------------------- OKF-Export
def _yaml_scalar(value):
"""Skalar so ausgeben, dass jeder YAML-Parser ihn wieder gleich liest."""
text = str(value)
heikel = (
not text
or text != text.strip()
or text[0] in "-?:,[]{}#&*!|>'\"%@`"
or ": " in text
or text.endswith(":")
or " #" in text
)
if not heikel:
return text
return '"' + text.replace("\\", "\\\\").replace('"', '\\"') + '"'
def _okf_actor(actor):
"""Deutsche Aktorkennung auf die Konvention aus OKF v0.2 §7 abbilden."""
for praefix, ersatz in ACTOR_OKF.items():
if actor.startswith(praefix):
return ersatz + actor[len(praefix):]
return actor
def _okf_description(body):
"""Ersten Satz der Kurzfassung ziehen. Kein Satz, kein Feld."""
zeilen, sammeln = [], False
for line in body.split("\n"):
if line.startswith("## "):
if sammeln:
break
sammeln = line[3:].strip().lower() == "kurzfassung"
continue
if sammeln:
if not line.strip() and zeilen:
break
if line.strip():
zeilen.append(line.strip())
text = " ".join(zeilen)
if not text:
return None
return _erster_satz(text)
def _erster_satz(text, maximum=400):
"""Ersten echten Satz zurückgeben, Abkürzungen und Zahlen respektierend.
Teilt sich die Satzende-Entscheidung mit ``satzsegmentierung/v1``; zwei
getrennte Logiken für dieselbe Frage würden garantiert auseinanderdriften.
"""
for treffer in SATZENDE_RE.finditer(text):
if not _wort_beendet_satz(_letztes_wort(text, treffer.start())):
continue
return text[:treffer.start()] + treffer.group(1)
return text if len(text) <= maximum else text[:maximum].rstrip() + " …"
def _okf_sources(fm, register, mit_quellen):
"""sources-Block nach §5.1 aus Frontmatter plus Registerzeile bauen."""
zeilen = []
for sid in fm.get("sources", []):
eintrag = register.get(sid, {})
if mit_quellen:
resource = "/" + eintrag.get("ablage", f"sources/raw/{sid}")
else:
# §5.1 erlaubt ausdrücklich einen nicht folgbaren Deskriptor. Die
# Rechte-Spalte ist Freitext; ob eine Ablage weitergegeben werden
# darf, entscheidet ein Mensch über --with-sources, nicht ein Regex.
resource = f"registered source {sid}, file not exported"
zeilen.append(f" - id: {sid}")
zeilen.append(f" resource: {_yaml_scalar(resource)}")
if eintrag.get("titel"):
zeilen.append(f" title: {_yaml_scalar(eintrag['titel'])}")
if _iso_date(eintrag.get("stand", "")):
zeilen.append(f" last_modified: {eintrag['stand']}")
zeilen.append(f" oksv_trust: {eintrag.get('trust', '?')}")
return zeilen
def _okf_extern_sources(fm, extern):
"""sources-Block für aufgeführte externe Bezugsquellen nach §5.1.
Ohne diesen Zweig verlässt eine ausschließlich extern belegte Seite den
Tresor ohne jede Quellenangabe — belegte Aussagen ohne Beleg, und genau
das ist der Kernwert, den der Export nicht verlieren darf.
Der Bindungspfad aus .vault-extern.json erscheint hier NIEMALS: er ist
host-lokal und hat außerhalb dieser Maschine keine Bedeutung.
"""
zeilen = []
for xid in fm.get("externe_quellen", []):
eintrag = extern.get(xid, {})
url = eintrag.get("url")
if url:
# Ein registriertes https-Präfix ist portabel und öffentlich —
# der einzige Fall, in dem eine externe Ressource folgbar ist.
resource = url
else:
titel = eintrag.get("titel") or xid
resource = f"external reference {xid}, {titel}, not exported"
zeilen.append(f" - id: {xid}")
zeilen.append(f" resource: {_yaml_scalar(resource)}")
if eintrag.get("titel"):
zeilen.append(f" title: {_yaml_scalar(eintrag['titel'])}")
if _iso_date(eintrag.get("stand", "")):
zeilen.append(f" last_modified: {eintrag['stand']}")
zeilen.append(f" oksv_trust: {eintrag.get('trust', '?')}")
zeilen.append(f" oksv_external_kind: {eintrag.get('art', '?')}")
return zeilen
def _okf_frontmatter(fm, body, register, concepts, mit_quellen, extern=None):
zeilen = ["---", f"type: {_yaml_scalar(fm.get('type', ''))}"]
if fm.get("title"):
zeilen.append(f"title: {_yaml_scalar(fm['title'])}")
description = _okf_description(body)
if description:
zeilen.append(f"description: {_yaml_scalar(description)}")
tags = fm.get("tags", [])
if tags:
zeilen.append("tags: [" + ", ".join(_yaml_scalar(t) for t in tags) + "]")
zeilen.append(f"status: {STATUS_OKF.get(fm.get('status'), 'stable')}")
if fm.get("geprueft_von") and fm.get("geprueft_am"):
# §5.2/§11: eine blanke Map gilt als einelementige Liste. Das Datum
# bleibt Kalendertag; ein aufgefülltes T00:00:00Z würde Präzision
# erfinden, die der Bestand nicht hat.
zeilen.append(
"verified: { by: %s, at: %s }"
% (_yaml_scalar(_okf_actor(fm["geprueft_von"])), fm["geprueft_am"])
)
quellen = (_okf_sources(fm, register, mit_quellen)
+ _okf_extern_sources(fm, extern or {}))
if quellen:
zeilen.append("sources:")
zeilen.extend(quellen)
# Producer-eigene Zusatzschlüssel, nach §4.1 ausdrücklich erlaubt. Der
# Präfix hält sie von v0.2-Standardfeldern fern.
zeilen.append(f"oksv_profile: {PROFIL}")
for feld in ("domain", "version", "confidence", "stand"):
if fm.get(feld):
zeilen.append(f"oksv_{feld}: {_yaml_scalar(fm[feld])}")
if fm.get("concepts"):
zeilen.append("oksv_concepts: [" + ", ".join(fm["concepts"]) + "]")
labels = [
concepts[b]["preferred"] for b in fm["concepts"] if b in concepts
]
if labels:
# Als Frontmatter-Liste, nicht als HTML-Kommentar im Rumpf: ein
# Label mit '-->' hätte den Kommentar geschlossen und alles
# dahinter zu sichtbarem Bundle-Inhalt gemacht. preferred wird
# schwächer geprüft als Claim-Text, deshalb bekommt es hier keinen
# Weg in den Rumpf.
zeilen.append(
"oksv_concept_labels: ["
+ ", ".join(_yaml_scalar(label) for label in labels) + "]"
)
# Das Trust-Tier wird bewusst NICHT geschrieben. KONZEPT.md sagt zu, dass
# es nur abgeleitet und nie gespeichert wird; ein Konsument leitet es nach
# §5.3 selbst aus verified ab. Es hier auszugeben wäre genau die
# Speicherung, die das Profil ausschließt.
zeilen.append("---")
return zeilen
def _okf_body(seite, register, extern=None, anchors=None):
"""Body verbatim, plus Fußnoten nach §5.1 und Beziehungen als Links."""
ausgabe = []
for line in seite["body"].split("\n"):
treffer = CLAIM_RE.match(line) if line.startswith(CLAIM_START) else None
ausgabe.append(f"{line}[^{treffer.group(2)}]" if treffer else line)
text = "\n".join(ausgabe).rstrip("\n")
if seite["relationen"]:
text += "\n\n## Beziehungen\n"
for relation in seite["relationen"]:
ziel = relation["ziel"][len("knowledge/"):]
name = Path(ziel).stem
text += f"\n- {relation['typ']}: [{_markdown_text(name)}](/{ziel})"
text += "\n"
extern = extern or {}
anchors = anchors or {}
verwendet = sorted({claim["quelle"] for claim in seite["claims"]})
if verwendet:
# Das Fußnotenlabel MUSS die Quellen-ID sein, nicht die C-ID: §5.1
# nennt sources[].id als Join-Key in die sources-Liste.
text += "\n\n"
for sid in verwendet:
if sid.startswith("X-"):
titel = extern.get(sid, {}).get("titel") or sid
# Ohne die Anker wäre die Fußnote im Bundle wertlos: der
# Satzwortlaut wandert nicht mit, also muss wenigstens der
# Zeiger auffindbar bleiben.
stellen = sorted({
(anchors.get(sid, {}).get("anchors", {})
.get(claim["anker"], {}).get("document"),
anchors.get(sid, {}).get("anchors", {})
.get(claim["anker"], {}).get("sentence_index"))
for claim in seite["claims"]
if claim["quelle"] == sid and claim.get("anker")
})
fundstellen = ", ".join(
f"{dokument} Satz {index}"
for dokument, index in stellen if dokument
)
if fundstellen:
titel = f"{titel} — {fundstellen}"
else:
titel = register.get(sid, {}).get("titel") or sid
text += f"[^{sid}]: {titel}\n"
return text.rstrip("\n") + "\n"
def _markdown_text(value):
"""Linktext so ausgeben, dass eine Klammer den Link nicht zerlegt."""
return (str(value).replace("\\", "\\\\")
.replace("[", "\\[").replace("]", "\\]"))
def _okf_index_root(domaenen, quelle_beschreibung):
zeilen = [
"---",
f'okf_version: "{OKF_VERSION}"',
"---",
"",
"# Bundle",
"",
quelle_beschreibung,
"",
"# Subdirectories",
"",
]
for domain in sorted(domaenen):
zeilen.append(f"* [{_markdown_text(domain)}]({domain}/) - Wissensdomäne des Tresors.")
return "\n".join(zeilen) + "\n"
def _okf_index_domain(domain, seiten):
zeilen = [f"# {domain}", ""]
for rp in sorted(seiten):
fm = seiten[rp]["fm"]
name = Path(rp).name
titel = fm.get("title") or Path(rp).stem
beschreibung = _okf_description(seiten[rp]["body"]) or "Wissensseite."
zeilen.append(f"* [{_markdown_text(titel)}]({name}) - {beschreibung}")
return "\n".join(zeilen) + "\n"
def _okf_log():
"""log.md in die §9-Form bringen: Datumsgruppen, neueste zuerst."""
if not _safe_regular_file(LOG):
return None
gruppen = {}
try:
log_text = read(LOG)
except (OSError, UnicodeError):
return None
for line in log_text.split("\n"):
treffer = re.match(r"^## \[(\d{4}-\d{2}-\d{2})\] ([a-z]+) \| (.+)$", line)
if not treffer:
continue
datum, aktion, text = treffer.groups()
gruppen.setdefault(datum, []).append((aktion, text))
if not gruppen:
return None
zeilen = ["# Directory Update Log", ""]
for datum in sorted(gruppen, reverse=True):
zeilen.append(f"## {datum}")
for aktion, text in gruppen[datum]:
zeilen.append(f"* **{aktion.capitalize()}**: {text}")
zeilen.append("")
return "\n".join(zeilen).rstrip("\n") + "\n"
def _export_ziel_pruefen(ziel: Path):
"""Fail-closed: kein Skill-Ladeort, nicht im Tresor, kein Fremdinhalt."""
lexikalisch = Path(os.path.abspath(ziel))
if lexikalisch.is_symlink():
return "Ziel ist ein Symlink"
# Containment und Ladeort erst nach dem Auflösen prüfen: ROOT ist selbst
# aufgelöst (Path(__file__).resolve()), und auf macOS liegt /var hinter
# einem Symlink auf /private/var. Ohne resolve() greift die Prüfung dort
# nie. Der lexikalische Pfad wird zusätzlich geprüft, damit auch ein
# buchstäblich benannter Ladeort auffällt.
aufgeloest = lexikalisch.resolve()
if aufgeloest == ROOT or ROOT in aufgeloest.parents:
return "Ziel liegt innerhalb des Tresors"
verboten = sorted(
(set(aufgeloest.parts) | set(lexikalisch.parts))
& EXPORT_VERBOTENE_SEGMENTE
)
if verboten:
return (
f"Ziel liegt in einem Skill-Ladeort ({', '.join(verboten)}); ein "
f"exportiertes Bundle hat keine Engine und keine Regeln und darf "
f"nicht als Skill geladen werden"
)
if not aufgeloest.exists():
return None
if not aufgeloest.is_dir():
return "Ziel existiert und ist kein Verzeichnis"
if not any(aufgeloest.iterdir()):
return None
if _ist_frueherer_export(aufgeloest):
return None
return (
"Ziel ist nicht leer und kein früherer OKF-Export "
"(erkannt am okf_version im Wurzel-index.md)"
)
def _ist_frueherer_export(ordner: Path) -> bool:
"""Wurzel-index.md mit okf_version im Frontmatter (§12).
Bewusst nicht über _safe_regular_file: das verlangt einen Pfad innerhalb
des Tresors, und das Exportziel liegt per Definition außerhalb. Die
Härtung (kein Symlink, echte einfach verlinkte Datei) gilt hier trotzdem.
"""
kandidat = ordner / "index.md"
try:
status = os.lstat(str(kandidat))
if not stat.S_ISREG(status.st_mode) or status.st_nlink != 1:
return False
zeilen = kandidat.read_text(encoding="utf-8").split("\n")
except (OSError, UnicodeError):
return False
if not zeilen or zeilen[0].strip() != "---":
return False
for line in zeilen[1:]:
if line.strip() == "---":
return False
if line.startswith("okf_version:"):
return True
return False
def cmd_export(ziel, mit_quellen=False):
"""Bestand als OKF-v0.2-Bundle außerhalb des Tresors ausgeben."""
fehler, _, seiten, _, register, _, extern_kontext = cmd_validate(still=True)
if fehler:
print("🔴 export: ABBRUCH — validate ist rot; erst den Bestand "
"reparieren.")
for f in fehler[:10]:
print(f" {f}")
return 1
manifest_fehler, _ = _manifest_status()
if manifest_fehler:
print("🔴 export: ABBRUCH — Stand entspricht nicht dem Manifest; "
"exportiert wird nur ein freigegebener Release.")
for f in manifest_fehler[:10]:
print(f" {f}")
return 1
_, concepts, concept_fehler = parse_concepts()
if concept_fehler:
print("🔴 export: ABBRUCH — Begriffswelten sind nicht valide.")
return 1
ziel_pfad = Path(os.path.abspath(ziel))
problem = _export_ziel_pruefen(ziel_pfad)
if problem:
print(f"🔴 export: ABBRUCH — {problem}.")
return 1
try:
version = read(VERSION).strip() if _safe_regular_file(VERSION) else "?"
except (OSError, UnicodeError):
version = "?"
herkunft = (
f"Export aus dem Wissenstresor (Profil {PROFIL}, Bestand v{version}). "
f"Dies ist eine Momentaufnahme in OKF {OKF_VERSION}, kein Tresor: sie "
f"trägt keine Engine, kein Manifest und keine Regeln. "
+ ("Registrierte Rohquellen liegen unter sources/raw/."
if mit_quellen else
"Registrierte Rohquellen sind nicht enthalten; sources[].resource "
"ist deshalb ein Deskriptor und kein folgbarer Pfad.")
)
dateien = {}
domaenen = {}
for rp, seite in sorted(seiten.items()):
domain = seite["fm"].get("domain", "unbekannt")
name = Path(rp).name
kopf = _okf_frontmatter(
seite["fm"], seite["body"], register, concepts, mit_quellen,
extern=extern_kontext["register"])
rumpf = _okf_body(seite, register,
extern=extern_kontext["register"],
anchors=extern_kontext["anchors"])
dateien[f"{domain}/{name}"] = "\n".join(kopf) + "\n" + rumpf
domaenen.setdefault(domain, {})[rp] = seite
dateien["index.md"] = _okf_index_root(domaenen, herkunft)
for domain, inhalt in sorted(domaenen.items()):
dateien[f"{domain}/index.md"] = _okf_index_domain(domain, inhalt)
log_text = _okf_log()
if log_text:
dateien["log.md"] = log_text
kopien = []
if mit_quellen:
for sid, eintrag in sorted(register.items()):
quelle, pfadfehler = _safe_relative_path(ROOT, eintrag.get("ablage", ""))
if pfadfehler or not quelle.is_file():
print(f"🔴 export: ABBRUCH — Ablage von {sid} ist nicht "
f"sicher lesbar.")
return 1
kopien.append((eintrag["ablage"], quelle))
# Erst vollständig in ein frisches Staging schreiben, dann das Ziel in
# einem Zug ersetzen. Das löst drei Dinge auf einmal: das Staging enthält
# keine Symlinks, also kann kein vorbereiteter Link im Zielordner den
# Schreibvorgang aus dem Ziel heraustragen; ein Abbruch hinterlässt keinen
# Halbstand; und ein früherer Export wird ersetzt statt übermischt, sodass
# keine verwaisten Dokumente aus einem alten Bestand liegen bleiben.
try:
ziel_pfad.parent.mkdir(parents=True, exist_ok=True)
staging = Path(tempfile.mkdtemp(
prefix=f".{ziel_pfad.name}.okf-staging-", dir=str(ziel_pfad.parent)
))
except OSError as exc:
print(f"🔴 export: ABBRUCH — Staging nicht anlegbar: {exc}")
return 1
verdraengt = None
try:
for rel_pfad in sorted(dateien):
datei = staging / rel_pfad
datei.parent.mkdir(parents=True, exist_ok=True)
datei.write_text(dateien[rel_pfad], encoding="utf-8")
for rel_pfad, quelle in kopien:
datei = staging / rel_pfad
datei.parent.mkdir(parents=True, exist_ok=True)
datei.write_bytes(quelle.read_bytes())
if ziel_pfad.exists():
verdraengt = Path(tempfile.mkdtemp(
prefix=f".{ziel_pfad.name}.okf-alt-", dir=str(ziel_pfad.parent)
))
os.rmdir(str(verdraengt))
os.rename(str(ziel_pfad), str(verdraengt))
try:
os.rename(str(staging), str(ziel_pfad))
except OSError:
if verdraengt is not None and not ziel_pfad.exists():
os.rename(str(verdraengt), str(ziel_pfad))
verdraengt = None
raise
except (OSError, UnicodeError) as exc:
shutil.rmtree(str(staging), ignore_errors=True)
if verdraengt is not None and verdraengt.exists():
shutil.rmtree(str(verdraengt), ignore_errors=True)
print(f"🔴 export: ABBRUCH — Schreiben fehlgeschlagen, Ziel "
f"unverändert: {exc}")
return 1
if verdraengt is not None:
shutil.rmtree(str(verdraengt), ignore_errors=True)
print(f"🟢 export: {len(dateien)} Dokumente"
+ (f" + {len(kopien)} Rohquellen" if kopien else "")
+ f" nach {ziel_pfad} geschrieben (OKF {OKF_VERSION}).")
print(" Der Zielordner wurde vollständig ersetzt, nicht ergänzt: ein "
"Export ist eine Momentaufnahme, kein gepflegter Bestand.")
print(" Einbahnstraße: der Tresor liest kein fremdes OKF zurück. "
"Rückweg ist der reguläre Ingest.")
if mit_quellen:
print(" Die kopierten Rohquellen sind byteidentisch und deshalb "
"keine OKF-Konzeptdokumente; mit --with-sources erfüllt das "
"Bundle §11 Bedingung 2 bewusst nicht (siehe "
"references/export-okf.md).")
else:
print(" Ohne --with-sources bleiben Rohquellen im Tresor; "
"Rechte klärt ein Mensch, nicht das Script.")
return 0
def cmd_doctor():
print("── doctor: Gesamtdiagnose ─────────────────────────────────────")
(fehler, warnungen, seiten, claims, register, router,
extern_kontext) = cmd_validate(still=True)
hinweise = []
if not _safe_regular_file(VERSION):
fehler.append("VERSION fehlt oder ist keine sichere reguläre Datei")
else:
try:
version_text = read(VERSION).strip()
except (OSError, UnicodeError) as exc:
version_text = None
fehler.append(f"VERSION ist nicht sicher als UTF-8 lesbar — {exc}")
if version_text is not None and not VERSION_RE.fullmatch(version_text):
fehler.append(f"VERSION {version_text!r} ist kein SemVer x.y.z")
if _safe_regular_file(INDEX):
try:
index_text = read(INDEX)
except (OSError, UnicodeError) as exc:
index_text = None
fehler.append(f"INDEX.md ist nicht sicher als UTF-8 lesbar — {exc}")
if index_text is not None and index_text != build_index(seiten):
fehler.append("INDEX.md weicht vom Bestand ab — 'vault.py index' ausführen (Drift)")
else:
fehler.append("INDEX.md fehlt oder ist keine reguläre Datei — 'vault.py index' ausführen")
if _safe_regular_file(GRAPH):
soll = json.dumps(build_graph(seiten), ensure_ascii=False, indent=2, sort_keys=True) + "\n"
try:
graph_text = read(GRAPH)
except (OSError, UnicodeError) as exc:
graph_text = None
fehler.append(f"graph/graph.json ist nicht sicher als UTF-8 lesbar — {exc}")
if graph_text is not None and graph_text != soll:
fehler.append("graph/graph.json weicht vom Bestand ab — 'vault.py graph' ausführen (Drift)")
else:
fehler.append("graph/graph.json fehlt oder ist keine reguläre Datei "
"— 'vault.py graph' ausführen")
if os.path.lexists(str(RELEASE_LOCK)):
fehler.append(".vault-release.lock vorhanden — laufenden/abgebrochenen Release prüfen")
# Router-Abdeckung und Orphans
gelistet = {s for sec in router.values() for s in sec["seiten"]}
verlinkt = {r["ziel"] for s in seiten.values() for r in s["relationen"]}
for rp in sorted(seiten):
if rp not in gelistet:
warnungen.append(f"{rp}: nicht im ROUTER gelistet — Seite ist unauffindbar per Map-first")
if rp not in gelistet and rp not in verlinkt:
warnungen.append(f"{rp}: Orphan — weder Router-Eintrag noch eingehende Relation")
# Schlagwort-Überschneidungen zwischen Domänen = Mischfragen-Signal
wo = {}
for d, sec in router.items():
for w in sec["schlagworte"]:
wo.setdefault(w, []).append(d)
for w, ds in sorted(wo.items()):
if len(ds) > 1:
hinweise.append(f"Schlagwort {w!r} in mehreren Domänen ({', '.join(sorted(ds))}) "
f"— Treffer in beiden ⇒ Mischfrage melden")
# Split-Kandidaten: kein Fehler, keine Warnung — nur ein deterministisches
# Signal, wann Kompressions- bzw. Beförderungsregel geprüft werden sollte.
# Splitten selbst bleibt Modellarbeit (Befüllen-Workflow), nie automatisch.
for rp, s in sorted(seiten.items()):
n_claims = len(s["claims"])
n_zeilen = s.get("zeilen", 0)
if n_claims > SPLIT_CLAIMS_SCHWELLE:
hinweise.append(f"{rp}: {n_claims} Claims (Schwelle {SPLIT_CLAIMS_SCHWELLE}) "
f"— Split-Kandidat: thematisch verwandte Claims ggf. in eigene "
f"Konzeptseite auslagern (Befüllen-Workflow, Beförderungsregel)")
if n_zeilen > SPLIT_ZEILEN_SCHWELLE:
hinweise.append(f"{rp}: Body {n_zeilen} Zeilen (Schwelle {SPLIT_ZEILEN_SCHWELLE}) "
f"— möglicher Verdichtungs-/Split-Kandidat, siehe Kompressionsregel")
# Prüfangabe: nur melden, wenn der Bestand das Feld überhaupt nutzt. Ein
# Tresor, der es gar nicht führt, ist nicht auffällig, sondern schlicht
# unverifiziert — dann wäre der Hinweis auf jeder Seite reines Rauschen.
# Hinweisstufe, damit ein Kalenderstand nie eine grüne Ampel kippt.
if any(s["fm"].get("geprueft_von") for s in seiten.values()):
for rp, s in sorted(seiten.items()):
fm = s["fm"]
if fm.get("confidence") == "hoch" and not fm.get("geprueft_von"):
hinweise.append(
f"{rp}: confidence hoch, aber keine Prüfangabe "
f"(Trust-Tier {TIER_UNVERIFIED}) — der Bestand nutzt "
f"geprueft_von bereits, diese Seite nicht")
print("── Externe Bezugsquellen ──────────────────────────────────────")
extern_register = extern_kontext["register"]
if not extern_register:
print(" keine aufgeführt — der Tresor liest ausschließlich sich selbst")
else:
bindung, bindungsfehler = parse_bindung()
fehler.extend(bindungsfehler)
for xid in sorted(extern_register):
zeile = extern_register[xid]
status = _extern_quelle_status(xid, zeile, bindung)
print(f" {xid} {zeile['art']:<16} {status['modus']}")
if status["modus"] == "unbound":
# Ungebunden ist KEIN Fehler: sonst wäre jedes frisch
# entpackte Paket auf jedem neuen Host rot, und AD-08 fiele.
# Fail-closed greift erst bei der Nutzung.
hinweise.append(f"{xid}: {status['grund']}")
continue
anker_datei = extern_kontext["anchors"].get(xid)
if not anker_datei or status["modus"] != "lokal":
continue
for aid in sorted(anker_datei["anchors"]):
anker = anker_datei["anchors"][aid]
text, _, grund = _lies_externes_dokument(
status["wurzel"], status["anker"], anker["document"])
if grund:
warnungen.append(
f"{xid}/{anker['document']}: nicht lesbar — {grund}")
continue
# Hash-first, Index nur als Hinweis: eine eingefügte Zeile
# verschiebt den Satz, bricht ihn aber nicht.
treffer = [i for i, _, satz in _saetze(text)
if _satz_digest(satz) == anker["text_sha256"]]
if not treffer:
warnungen.append(
f"{xid}/{aid}: zitierter Satz nicht mehr gefunden "
f"(Drift) — der Beleg braucht Kuratierung")
elif anker["sentence_index"] not in treffer:
warnungen.append(
f"{xid}/{aid}: Satz steht jetzt an Position "
f"{treffer[0]} statt {anker['sentence_index']} "
f"(verschoben, nicht gebrochen)")
print("── Prüfsummen ─────────────────────────────────────────────────")
if cmd_checksum(verify=True) != 0:
fehler.append("MANIFEST.sha256 fehlt, ist ungültig oder weicht vom Bestand ab")
print("── Zusammenfassung ────────────────────────────────────────────")
for f in fehler:
print(f"🔴 FEHLER {f}")
for w in warnungen:
print(f"🟡 WARNUNG {w}")
for h in hinweise:
print(f"ℹ️ {h}")
ampel = "🔴" if fehler else ("🟡" if warnungen else "🟢")
print(f"{ampel} doctor: {len(fehler)} Fehler, {len(warnungen)} Warnungen, "
f"{len(hinweise)} Hinweise — {len(seiten)} Seiten / {len(claims)} Claims / "
f"{len(register)} Quellen.")
return 1 if fehler else 0
def main():
ap = argparse.ArgumentParser(prog="vault.py", description=__doc__,
formatter_class=argparse.RawDescriptionHelpFormatter)
sub = ap.add_subparsers(dest="cmd", required=True)
sub.add_parser("validate")
sub.add_parser("index")
sub.add_parser("graph")
s = sub.add_parser("search")
s.add_argument("begriffe", nargs="+")
query_parser = sub.add_parser("query")
query_parser.add_argument("frage", nargs="+")
query_parser.add_argument("--world")
query_parser.add_argument("--limit", type=int, default=8)
# Ohne dieses Flag verlässt kein Byte den Skill-Ordner. Es macht am
# Aufruf sichtbar, dass hier bewusst live nachgeschlagen wird.
query_parser.add_argument("--extern", action="store_true")
query_parser.add_argument("--source", dest="quelle", action="append")
# Vollsichtung: ohne Schalter der Plan, mit --batch ein Stapel samt
# Siegel, mit --receipt die Prüfung der Quittung.
sweep_parser = sub.add_parser("sweep")
# Die Frage ist formal optional, damit ihr Fehlen als JSON-Zustand endet
# und nicht als Usage-Text: --receipt nimmt alle folgenden Wörter als
# Einträge, eine Frage dahinter wäre sonst still verschluckt.
sweep_parser.add_argument("frage", nargs="*")
sweep_parser.add_argument("--batch", type=int)
# 'extend': Wer je Stapel ein eigenes --receipt setzt, etwa beim
# Einsammeln von Subagenten, bekommt alle Einträge gewertet.
sweep_parser.add_argument("--receipt", nargs="*", action="extend")
sweep_parser.add_argument("--size", type=int,
default=SWEEP_STANDARD_GROESSE)
sweep_parser.add_argument("--domain", dest="domaene", action="append")
sweep_parser.add_argument("--page", dest="seite", action="append")
media_parser = sub.add_parser("media-template")
media_parser.add_argument("source_id")
extern_parser = sub.add_parser("extern")
extern_parser.add_argument("aktion", choices=["list", "bind", "unbind"])
extern_parser.add_argument("source_id", nargs="?")
extern_parser.add_argument("pfad", nargs="?")
anchor_parser = sub.add_parser("anchor-template")
anchor_parser.add_argument("source_id")
anchor_parser.add_argument("dokument")
orchestrator_parser = sub.add_parser("orchestrator-template")
orchestrator_parser.add_argument("source_id")
c = sub.add_parser("checksum")
c.add_argument("--verify", action="store_true")
l = sub.add_parser("log")
l.add_argument("aktion")
l.add_argument("text")
sub.add_parser("stats")
q = sub.add_parser("source")
q.add_argument("datei")
sub.add_parser("doctor")
r = sub.add_parser("route")
r.add_argument("frage", nargs="+")
v = sub.add_parser("release")
v.add_argument("stufe", nargs="?", default="patch",
choices=["major", "minor", "patch"])
e = sub.add_parser("export")
e.add_argument("--okf", action="store_true", required=True)
e.add_argument("--out", required=True)
e.add_argument("--with-sources", action="store_true")
a = ap.parse_args()
if a.cmd == "validate":
fehler, *_ = cmd_validate()
sys.exit(1 if fehler else 0)
elif a.cmd == "index":
sys.exit(cmd_index())
elif a.cmd == "graph":
sys.exit(cmd_graph())
elif a.cmd == "search":
sys.exit(cmd_search(a.begriffe))
elif a.cmd == "query":
if not 1 <= a.limit <= MAX_QUERY_LIMIT:
result = _query_base(
" ".join(a.frage), "invalid_query",
errors=[f"--limit muss zwischen 1 und {MAX_QUERY_LIMIT} liegen"],
)
_emit_query_json(result)
sys.exit(2)
sys.exit(cmd_query(a.frage, world=a.world, limit=a.limit,
extern=a.extern, quellen_filter=a.quelle))
elif a.cmd == "sweep":
sys.exit(cmd_sweep(a.frage, batch=a.batch, receipt=a.receipt,
groesse=a.size, domaenen=a.domaene,
seiten=a.seite))
elif a.cmd == "media-template":
sys.exit(cmd_media_template(a.source_id))
elif a.cmd == "extern":
if a.aktion != "list" and not a.source_id:
print("🔴 extern: bind/unbind brauchen eine X-nnnn")
sys.exit(1)
if a.aktion == "bind" and not a.pfad:
print("🔴 extern: bind braucht einen absoluten Pfad")
sys.exit(1)
sys.exit(cmd_extern(a.aktion, a.source_id, a.pfad))
elif a.cmd == "anchor-template":
sys.exit(cmd_anchor_template(a.source_id, a.dokument))
elif a.cmd == "orchestrator-template":
sys.exit(cmd_orchestrator_template(a.source_id))
elif a.cmd == "checksum":
sys.exit(cmd_checksum(verify=a.verify))
elif a.cmd == "log":
sys.exit(cmd_log(a.aktion, a.text))
elif a.cmd == "stats":
sys.exit(cmd_stats())
elif a.cmd == "source":
sys.exit(cmd_source(a.datei))
elif a.cmd == "doctor":
sys.exit(cmd_doctor())
elif a.cmd == "route":
sys.exit(cmd_route(a.frage))
elif a.cmd == "release":
sys.exit(cmd_release(a.stufe))
elif a.cmd == "export":
sys.exit(cmd_export(a.out, mit_quellen=a.with_sources))
if __name__ == "__main__":
main()
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| canvas-designanthropics/skillsCreate beautiful visual art in .png and .pdf documents using design philosophy. You should use this skill when the user asks to create a poster, piece of art, design, or other static piece. Create original visual designs, never copying existing artists' work to avoid copyright violations. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| docxanthropics/skillsUse this skill whenever the user wants to create, read, edit, or manipulate Word documents (.docx files) or Word templates (.dotx files). Triggers include: any mention of 'Word doc', 'word document', '.docx', '.dotx', or requests to produce professional documents with formatting like tables of contents, headings, page numbers, or letterheads. Also use when extracting or reorganizing content from .docx or .dotx files, inserting or replacing images in documents, performing find-and-replace in Word files, working with tracked changes or comments, or converting content into a polished Word document. If the user asks for a 'report', 'memo', 'letter', 'template', or similar deliverable as a Word or .docx file, use this skill. Do NOT use for PDFs, spreadsheets, Google Docs, or general coding tasks unrelated to document generation. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| pdfanthropics/skillsUse this skill whenever the user wants to do anything with PDF files. This includes reading or extracting text/tables from PDFs, combining or merging multiple PDFs into one, splitting PDFs apart, rotating pages, adding watermarks, creating new PDFs, filling PDF forms, encrypting/decrypting PDFs, extracting images, and OCR on scanned PDFs to make them searchable. If the user mentions a .pdf file or asks to produce one, use this skill. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| pptxanthropics/skillsUse this skill any time a .pptx or .potx file is involved in any way — as input, output, or both. This includes: creating slide decks, pitch decks, or presentations; reading, parsing, or extracting text from any .pptx or .potx file (even if the extracted content will be used elsewhere, like in an email or summary); editing, modifying, or updating existing presentations; combining or splitting slide files; working with templates (.potx), layouts, speaker notes, or comments. Trigger whenever the user mentions "deck," "slides," "presentation," or references a .pptx or .potx filename, regardless of what they plan to do with the content afterward. If a .pptx or .potx file needs to be opened, created, or touched, use this skill. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |