matrx-content-guard 0.1.0__tar.gz

matrx_content_guard-0.1.0/.gitignore

@@ -0,0 +1,271 @@
+*.pyc
+secrets/
+ignore/
+temp/
+logs/
+# The broad `logs/` rule above is for RUNTIME log output, but it also matched
+# the dashboard's SOURCE directory and silently swallowed an entire feature's
+# files (only the pre-existing index.tsx stayed tracked), breaking the prod
+# Docker build with "Could not resolve ./structured-tab". Re-include the source.
+!apps/dashboard/src/features/logs/
+!apps/dashboard/src/features/logs/**
+todo
+text_notes/
+aidream/secrets/2.env
+automation_matrix/matrix_processing/temp/*
+cd
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+.venv/
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+# The blanket lib/ rule above is from the standard Python .gitignore template
+# and was silently swallowing TS source under the SPA `src/lib/` folders.
+# Re-allow them explicitly so frontend builds don't ship without their lib layer.
+!apps/dashboard/src/lib/
+!apps/dashboard/src/lib/**
+!apps/workflow-studio/src/lib/
+!apps/workflow-studio/src/lib/**
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+ai/tests/clean_response.json
+ai/tests/cx_storage_response.json
+ai/tests/execution_test.py
+ai/tests/final_response.json
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/#use-with-ide
+.pdm.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.env_remote
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+.env.armanonly
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# random armani files
+/armani_dev/secrets/
+/armani/
+/_armani/
+
+
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+.idea/
+.vscode/
+/node_modules/
+
+# Frontend pnpm workspace (apps/) — node_modules at the workspace root and any
+# member, plus Vite caches and build output. The unified lockfile (apps/pnpm-lock.yaml)
+# IS committed; everything below is regenerated.
+node_modules/
+apps/**/.vite/
+apps/**/dist/
+.vite/
+
+dump.rdb
+
+frontend/
+
+# AME Temp Files and directory structure
+# Ignore all files in the temp directory and its subdirectories
+/temp/**/*
+/tmp/**/*
+
+# Allow .gitkeep files to retain directory structure
+!/temp/**/.gitkeep
+!/tmp/**/.gitkeep
+
+# Armani
+.history*
+.history/
+local_data/
+local_reports_data/
+webscraper/quick_scrapes/temp/
+automation_matrix/ai_apis/fireworks/_dev/*
+automation_matrix/ai_apis/fireworks/_dev/fireworks_sample.py
+*.pdf
+*.flac
+*.mp3
+*.wav
+miniconda.sh
+/database/python_sql/temp_data/
+ .history*
+ .history/
+.history/
+
+_dev/
+/_dev/
+requirements_filtered.txt
+
+# matrx-dev-tools backups
+.env-backups/
+# Matrx Ship config (contains API key)
+.matrx-ship.json
+
+# Matrx config (contains API keys)
+.matrx.json
+.matrx-tools.conf
+
+# Claude Code local worktrees and per-user settings
+.claude/worktrees/
+.claude/settings.local.json
+
+# Append-only snapshots from matrx_utils.update_history (unbounded; do not commit)
+common/utils/data_in_code/data_history.json
+packages/matrx-utils/matrx_utils/data_in_code/data_history.json
+
+# Tool-dispatch debug logs — one file per server start, never committed
+.matrx-debug/
+
+# macOS Finder metadata
+.DS_Store
+**/.DS_Store
+
+# Environment files
+.env
+.env.*
+*.env
+*.env.*
+
+# Keep safe templates trackable
+!.env.example
+!.env.sample
+!.env.template

matrx_content_guard-0.1.0/AUDIT_RESULTS.md

@@ -0,0 +1,24 @@
+# matrx-content-guard — live audit results
+
+Run: 2026-07-11T14:05:12.180277+00:00
+Project: `viyklljfdhtidwecakwx` (CMS). Read-only. No content persisted — ids/rule-ids/counts only.
+
+## Row counts checked
+
+- `html_pages`: 242 rows
+- `client_pages`: 23 rows
+- `client_components`: 2 rows
+- `client_sites`: 2 rows
+
+## Result: 285 content fields validated, 0 blocked
+
+**Zero blocked fields.** Every live content field on the CMS project validates `blocked=False` under its `standard` profile.
+
+## Warning frequency (advisory only — never blocks under `standard`)
+
+| rule_id | occurrences |
+|---|---|
+| `html.event_handler_attribute` | 140 |
+| `html.external_resource_origin` | 107 |
+| `js.inner_html_assignment` | 22 |
+| `html.parser_recovered` | 12 |

matrx_content_guard-0.1.0/CONTRACT.md

@@ -0,0 +1,188 @@
+# CONTRACT — matrx-content-guard (C3)
+
+> Published day 1, 2026-07-09. Owner: P3 (Safety & patch engine). Consumers: P2 (dry-run UX,
+> `cms_inspect.rules`), P1 (fail-closed write-boundary hook). Master plan: `../../docs/cms_agent_authoring/README.md`.
+
+## Authority rule
+
+**P1's service-layer hook is authoritative. Tool-layer validation (P2) is advisory/dry-run UX.**
+A P2 tool calling `validate_patch`/`validate_content` before writing is a courtesy to the agent
+(fast feedback, no wasted round trip) — it is NOT the enforcement point. P1's services MUST call
+`validate_content` (or reject via the injected hook) at the actual write boundary, fail-closed, even
+if P2 already checked. Two callers computing the same profile via `profile_for` guarantees they never
+disagree about *which* policy applies; each still independently decides whether to persist.
+
+## Public API
+
+All five surface as top-level imports: `from matrx_content_guard import ...`.
+
+```python
+def validate_content(
+    content: str,
+    profile: str,                                  # "name:variant" or bare "name" (-> :standard)
+    exceptions: list[ContentException] | None = None,
+) -> ValidationReport: ...
+
+def apply_patch(
+    original: str,
+    patch: SearchReplacePatch | UnifiedDiffPatch,   # the `Patch` union
+    *,
+    dry_run: bool = False,
+) -> PatchResult: ...
+
+def validate_patch(
+    original: str,
+    patch: SearchReplacePatch | UnifiedDiffPatch,
+    profile: str,
+    *,
+    exceptions: list[ContentException] | None = None,
+) -> ValidatePatchResult: ...
+
+def describe_policy(profile: str) -> dict: ...
+
+def profile_for(system: str, entity: str, field: str) -> str: ...  # raises KeyError, never silently defaults
+```
+
+All five functions are pure: no DB access, no network, no filesystem I/O, no imports from `aidream`
+or any tool framework. Same inputs -> byte-identical outputs, always.
+
+## Models
+
+### `Severity` (str enum)
+`"warning"` | `"block"`. Only `"block"` (after exception resolution) sets `ValidationReport.blocked`.
+
+### `Violation`
+| field | type | meaning |
+|---|---|---|
+| `rule_id` | `str` | key into the rule registry (`matrx_content_guard.rules.RULES`) |
+| `node_path` | `str` | HTML: lxml xpath (`/html/body/div[2]/script[1]`, `.../@href` for an attribute). CSS/JS: `"<prefix>:<line>:<col>"`. |
+| `excerpt` | `str` | ≤200 chars, the offending snippet |
+| `severity` | `Severity` | resolved for the profile that produced it |
+| `fix_hint` | `str` | plain-English, actionable |
+
+### `ValidationReport`
+| field | type | meaning |
+|---|---|---|
+| `blocked` | `bool` | `True` iff `violations` is non-empty after exceptions are applied |
+| `violations` | `list[Violation]` | BLOCK-severity, NOT excepted — these are what actually blocks |
+| `warnings` | `list[Violation]` | WARNING-severity — never blocks, always surfaced |
+| `excepted` | `list[Violation]` | BLOCK-severity findings suppressed by a matching `ContentException` — **never silently dropped**, always visible here for audit (extension beyond the brief's literal two-list spec, kept because "loud recovery, no silent defaults" is a repo-wide mandate) |
+| `profile` | `str` | the resolved `"name:variant"` key that was actually applied |
+
+### Patch models
+- `SearchReplaceHunk { search: str, replace: str }`
+- `SearchReplacePatch { format: "search_replace", hunks: list[SearchReplaceHunk] }`
+- `UnifiedDiffPatch { format: "unified_diff", diff: str }` — a standard unified-diff string; converted
+  internally to search/replace hunks (context+removed -> context+added) and applied through the
+  identical matcher, so both formats give identical failure-context quality.
+- `Patch = SearchReplacePatch | UnifiedDiffPatch`
+- `PatchFailureReason` (str enum): `"no_match"` | `"ambiguous_match"` | `"malformed_diff"`
+- `PatchFailure { hunk_index, reason, match_count, positions: list[int], closest_match: str|None, closest_match_position: int|None, closest_match_similarity: float|None, message }`
+- `PatchStats { hunks_total, hunks_applied, chars_before, chars_after, lines_changed }`
+- `PatchResult { applied: bool, result: str|None, failures: list[PatchFailure], stats: PatchStats, dry_run: bool }`
+  — `result` is `None` unless **every** hunk applied (all-or-nothing). `dry_run` is echoed from the
+  call for the caller's audit trail; `apply_patch` has no I/O either way, so it doesn't change what's
+  computed — only the caller's own write-boundary decides whether to persist `result`.
+- `ValidatePatchResult { patch: PatchResult, validation: ValidationReport|None }` — `validation` is
+  `None` iff the patch itself failed to apply (nothing to validate).
+
+### `ContentException` (the F3 exception/approval data shape)
+| field | type | engine-checked? | meaning |
+|---|---|---|---|
+| `rule_id` | `str` | yes | exact match required |
+| `scope_site_id` | `str\|None` | **no** | store-schema/informational only — see below |
+| `scope_page_id` | `str\|None` | **no** | store-schema/informational only — see below |
+| `match_node_path_prefix` | `str\|None` | yes | violation's `node_path` must start with this |
+| `match_excerpt_contains` | `str\|None` | yes | violation's `excerpt` must contain this substring |
+| `status` | `str` | yes | only `"approved"` is ever honored |
+| `note` | `str\|None` | no | free text |
+
+**Scoping is two-tier.** Site/page granularity is resolved by the CALLER, not this engine: P1's
+service layer knows which site/page it's writing to, queries only the exception rows in scope for
+that write, and passes just those into `validate_content`/`validate_patch`. The engine never sees a
+site_id/page_id and never filters on them. Rule + node granularity IS engine-checked: `rule_id` is
+always exact; `match_node_path_prefix`/`match_excerpt_contains` optionally narrow an already-in-scope
+exception to one subtree/snippet instead of blanket-suppressing the rule everywhere in the content.
+
+**Store:** a small table on the CMS project (`viyklljfdhtidwecakwx`), owned by P1, schema coordinated
+against this shape — migration + shared ledger rules apply (master plan §6.10). **Review/approve UI:**
+P5. This package owns only the shape and the matching semantics
+(`matrx_content_guard.exceptions.exception_matches` / `apply_exceptions`).
+
+## Profiles
+
+Five names × two variants = ten resolvable keys. A bare name resolves to `:standard`.
+
+| name | content_kind | is_fragment | maps to (via `profile_for`) |
+|---|---|---|---|
+| `html_page_document` | full HTML document | no | `html_pages.html_content` |
+| `cms_page_fragment` | HTML fragment | yes | `client_pages.html_content[_draft]` |
+| `cms_component_fragment` | HTML fragment | yes | `client_components.html_content[_draft]` |
+| `css` | CSS text | n/a | `client_pages.css_content[_draft]`, `client_components.css_content[_draft]`, `client_sites.global_css` |
+| `js` | JS text | n/a | `client_pages.js_content[_draft]` |
+
+`standard` is permissive-first (F3): every rule's default severity was calibrated against the live
+corpus (239 `html_pages` + 19 `client_pages` rows, audited 2026-07-09) so **inline `<script>` (73
+rows), event-handler attributes (40 rows), and external `<iframe>`/`<script src>` embeds (7 rows) all
+validate `blocked=false`.** `strict` today makes exactly one change: `html.event_handler_attribute`
+escalates from WARNING to BLOCK (for a future tighter surface, e.g. a public template gallery — no
+current caller uses `strict`). Profiles are pure data (`matrx_content_guard/profiles.py`) — a future
+policy change is a data edit, never an engine change.
+
+## Rule registry
+
+Every rule a violation can cite lives in `matrx_content_guard.rules.RULES`, one entry per `rule_id`,
+each with a `category`, a ≤140-char plain-English `summary`, a `fix_hint`, and a `default_severity`.
+`describe_policy(profile)` resolves each rule's *actual* severity for that profile/variant. See the
+module for the full, current list (17 rules as of 2026-07-09) — adding a rule is one dict entry plus
+the check that fires it; there is no second place severities live.
+
+**Hard-block minimum (BLOCK in every variant, zero live false positives as of 2026-07-09):**
+`html.denied_tag` (`<base>` only today), `html.dangerous_url_scheme` (`javascript:`/`vbscript:` in
+any URL-bearing attribute, browser-style scheme-sniffing so `java\tscript:` doesn't bypass it),
+`html.iframe_html_data_uri`, `html.css_expression_injection`, `html.css_javascript_url`,
+`css.expression_injection`, `css.javascript_url`.
+
+**Permissive/warn-only (never blocks under `standard`):** inline event handlers, external
+script/iframe/form/link origins, `@import`/`url()` external origins, parser-recovered-from-malformed-
+markup, and the entire `js.*` family (pattern-tier lint — `eval`, `document.write`, `new Function`,
+`innerHTML=` — **JS static analysis is an explicit non-goal**; these never escalate to BLOCK in any
+variant).
+
+## Parser / engine boundaries (read before extending)
+
+- **HTML:** `lxml.html` with `recover=True`. Validation walks the PARSED tree for reporting ONLY.
+  `apply_patch` never parses anything — pure string search/replace. A byte in storage never
+  round-trips through the HTML parser on write; this is the hard byte-preservation guarantee.
+- **Fragments vs documents:** each profile declares `is_fragment`; fragments parse via
+  `lxml.html.fragment_fromstring(..., create_parent="div")` (always succeeds, one synthetic root for
+  stable xpaths), documents via `lxml.html.document_fromstring` (fills in missing `<html>`/`<body>`
+  when absent — covers the one live `html_pages` row with no doctype).
+- **CSS:** bounded-regex pattern scans (`expression()`, `url()`, `@import`), not a full CSS parser.
+  Every pattern uses only bounded/non-nested quantifiers — no catastrophic-backtracking path — and
+  `PATTERN_SCAN_MAX_CHARS` (2,000,000) caps worst-case work regardless of document size, firing a
+  `content.pattern_scan_truncated` WARNING rather than silently skipping.
+- **JS:** pattern-tier lint only, explicitly bounded — no parser, no AST, never BLOCK. Documented
+  non-goal per the brief.
+
+## Wiring status (2026-07-09, live end-to-end as of this commit)
+
+- **P2 is wired and live.** `aidream/tools/_cms_shared.py::content_guard()` lazily imports
+  `matrx_content_guard` and finds every C3 entry point (verified: `cms_inspect_tool.py` calls
+  `guard.describe_policy(...)` / `guard.PROFILE_NAMES`; `cms_page_tool.py`'s dry-run patch preview
+  calls `guard.profile_for("cms", "page", field)` and `guard.validate_patch(...)` — both using this
+  package's canonical vocabulary directly, no hand-translation).
+- **P1's write-boundary hook is wired and live** — `aidream/package_integration.py::_configure_cms()`
+  imports `matrx_content_guard` and calls `configure_cms(content_validator=_ContentGuardAdapter(),
+  profile_resolver=matrx_content_guard.profile_for)`, replacing P1's interim placeholders wholesale as
+  their own docstrings said this package would. `_ContentGuardAdapter.validate_content` is a one-line
+  delegation to `matrx_content_guard.validate_content` — every CMS content-bearing write now fails
+  closed on a blocked report via `enforce_content`, not just P2's dry-run preview. Verified: this
+  package's `validate_content`/`validate_patch` accept the exceptions shape P1's `ContentValidator`
+  Protocol types as `list[dict]` (coerced via `exceptions.coerce_exceptions` — added after confirming
+  a raw dict would otherwise crash with `AttributeError`, since no exception store exists yet to have
+  caught this in practice).
+- This package is complete, installed (`packages/matrx-content-guard`, in the root `uv` workspace +
+  `pyproject.toml` deps), 128 tests passing, live-audited (0/280 real content fields blocked,
+  `AUDIT_RESULTS.md`), and adversarially reviewed (4 confirmed bypasses found and fixed — see
+  `FEATURE.md`'s "Security hardening" note) as of this commit.

matrx_content_guard-0.1.0/FEATURE.md

@@ -0,0 +1,104 @@
+# FEATURE.md — matrx-content-guard
+
+> Durable design notes. The typed contract lives in `CONTRACT.md` (C3) — read that first for the
+> API. This file is the WHY behind the choices, for whoever extends this package next.
+
+## What this is
+
+The deterministic validation + patch/diff engine every CMS agent mutation flows through
+(`html_pages.html_content`, `client_pages.*_content[_draft]`, `client_components.*_content[_draft]`,
+`client_sites.global_css`). Pure Python, zero DB access, zero tool-framework imports — a library, not
+a service. Two jobs: (1) walk content and report policy violations, (2) apply agent-authored
+search/replace or unified-diff patches to stored content.
+
+## Why permissive-first (F3)
+
+Arman's explicit failure mode: rules so restrictive that nobody wants to build websites on the
+platform. The live corpus (239 `html_pages` + 21 `client_pages` as of 2026-07-09, up from 19 at
+brief-time — `client_pages` grows) already contains inline `<script>` (73 rows), event-handler
+attributes (138 field-hits), and external `<iframe>`/`<script src>` embeds (107 field-hits) — all of
+that is normal, legitimate content, not an attack. The hard-block list is therefore deliberately tiny
+and picked for near-zero false-positive risk: a `javascript:`/`vbscript:` URL, a CSS
+`expression()`/`url(javascript:...)`, an HTML-data-URI iframe, and the `<base>` tag. Everything else
+(event handlers, external origins, JS pattern hits) is WARNING — visible, never blocking. See
+`rules.py`'s module docstring for the full reasoning per rule.
+
+## Why lxml over html5lib
+
+C-speed matters (some live rows are 200KB+ and get walked on every mutation), `recover=True` already
+tolerates everything actually seen in production (including the one row with no `<!doctype>`/`<html>`
+at all), and `getroottree().getpath(el)` gives a free, stable node path. html5lib's closer-to-a-real-
+browser error correction wasn't worth the speed cost for content this well-behaved. If a future
+pathological doc needs browser-exact recovery, that's the first thing to revisit.
+
+## Security hardening (2026-07-09, adversarial review)
+
+An adversarial subagent review targeting bypass techniques against the hard-block rules found and
+confirmed four real gaps, all fixed the same day (regression tests in the matching `test_*.py`):
+
+1. **`xlink:href` (any `prefix:href`/`prefix:src`) bypassed the hard-block entirely.** lxml's HTML
+   parser doesn't resolve XML namespaces, so `xlink:href` is literally the attribute name
+   `"xlink:href"` — comparing against `"href"` misses it completely. A classic real-world XSS bypass
+   technique targets exactly this gap. Fixed in `html_engine.py` by matching on the attribute's local
+   name (after the last `:`) instead of the raw name.
+2. **`<iframe srcdoc="...">` was entirely unscanned** despite being the same risk class as the
+   already-blocked `data:text/html` iframe `src` (both create an executing nested browsing context
+   from inline markup). Fixed by recursively scanning `srcdoc` content under the same profile
+   (`MAX_SRCDOC_DEPTH = 6` backstop against pathological nesting), rather than blanket-denying the
+   attribute — a legitimate `srcdoc` embed is still only flagged for what it actually contains.
+3. **CSS comments (`/**/`) and unicode escapes (`\65`) could split the literal `"expression("` /
+   `"javascript:"` strings past the hard-block regexes.** Real-world exploitability against THIS
+   platform's evergreen-browser-served pages is near-nil (modern browsers don't execute either
+   construct via CSS regardless), but the package's own contract calls these a hard BLOCK, so
+   `css_engine.py::_deobfuscate` now strips comments and decodes CSS unicode escapes before matching
+   — belt-and-suspenders for any non-evergreen consumer (legacy webviews, PDF renderers, email
+   clients) that might still honor them.
+4. **An exception's `match_node_path_prefix`/`match_excerpt_contains` set to `""` silently behaved as
+   an always-match wildcard**, identical to a much broader "no constraint" — a likely footgun for any
+   UI/serializer that sends `""` instead of omitting an unset field, silently widening an approver's
+   intended narrow scope. `exceptions.py::exception_matches` now treats blank strings identically to
+   `None` in both fields.
+
+Also hardened: `validate_content`/`validate_patch` now accept exceptions as plain `dict`s as well as
+`ContentException` instances (`exceptions.coerce_exceptions`) — P1's own `ContentValidator` Protocol
+types its `exceptions` param as `list[dict]`, and any real DB-backed exception store will round-trip
+as dicts too; the strict-model-only version would have crashed with `AttributeError` the moment either
+path carried a non-empty exceptions list.
+
+## The byte-preservation split (the one invariant that can't regress)
+
+Validation and patching are two completely separate code paths that never touch each other's data:
+`html_engine.py`/`css_engine.py`/`js_engine.py` PARSE content (via lxml / regex) to build a report —
+the parsed tree is discarded, never serialized back out. `patch.py` operates on the raw string ONLY —
+no parser anywhere in that file. A byte in storage that a patch didn't explicitly target is therefore
+*guaranteed* unchanged, because nothing in the write path ever round-trips content through a parser.
+If you're ever tempted to "normalize" or "pretty-print" content on write inside this package — don't;
+that's exactly the bug this split exists to prevent (brief gotcha (a)).
+
+## Where the F3 exception store actually lives
+
+This package only defines the shape (`ContentException`) and the matching semantics
+(`exceptions.py`). The actual table is P1's (`aidream/services/cms/`, coordinated schema, migration +
+ledger rules per master plan §6.10) and the approve/review UI is P5's. `validate_content` takes
+already-scoped-by-the-caller exceptions — it never queries anything.
+
+## Coordination gap as of this commit (see CONTRACT.md "Wiring status")
+
+P1 already built the consumer seam (`aidream/services/cms/validation.py` + `profiles.py`) with
+interim, hand-mapped placeholders that predate this package. Wiring the real thing in is P1's job
+(directory ownership), but there are two shape mismatches to close — documented in detail in
+`CONTRACT.md`. P2 hasn't wired `cms_inspect.rules` (`describe_policy`) or dry-run (`validate_patch`)
+yet either.
+
+## Extending this package
+
+- **New rule:** one entry in `rules.py::RULES` (id, category, ≤140-char summary, fix_hint,
+  default_severity) + the check that fires it (in `html_engine.py`/`css_engine.py`/`js_engine.py`) +
+  a test in the matching `test_*_engine.py`. Never invent a second place for severity/copy.
+- **New profile:** add to `profiles.py::_CONTENT_KIND_BY_NAME` (+ any `severity_overrides`) — profiles
+  are pure data, a policy change should never touch engine code.
+- **New content field:** one entry in `field_map.py::_FIELD_PROFILE_MAP`. `profile_for` raises loudly
+  on anything unmapped — that's intentional, never add a silent default branch.
+- **Re-running the live audit:** `scripts/audit_live_content.py` (needs `SUPABASE_CMS_*` env vars,
+  read-only) — re-proves the "0 blocked fields" guarantee as content grows; output committed to
+  `AUDIT_RESULTS.md`.

matrx_content_guard-0.1.0/PKG-INFO

@@ -0,0 +1,46 @@
+Metadata-Version: 2.4
+Name: matrx-content-guard
+Version: 0.1.0
+Summary: Deterministic HTML/CSS/JS content validation + patch/diff editing engine for the Matrx CMS agent-authoring layer
+Project-URL: Homepage, https://github.com/AI-Matrix-Engine/aidream-current
+Project-URL: Repository, https://github.com/AI-Matrix-Engine/aidream-current
+Author-email: Matrx <admin@aimatrx.com>
+Maintainer-email: Matrx <admin@aimatrx.com>
+License: MIT
+Keywords: cms,content-validation,html-sanitization,matrx,patch-diff
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Text Processing :: Markup :: HTML
+Requires-Python: >=3.13
+Requires-Dist: lxml>=5.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: tinycss2>=1.3
+Description-Content-Type: text/markdown
+
+# matrx-content-guard
+
+Deterministic HTML/CSS/JS content validation + patch/diff editing for the
+Matrx CMS agent-authoring layer. Pure Python, no DB access, no tool-framework
+imports — every agent mutation to `html_pages` / `client_*` content flows
+through this library before it's written.
+
+See `CONTRACT.md` for the full typed API and `FEATURE.md` for the durable
+design notes (parser choice, permissive-first policy rationale, byte-
+preservation guarantee).
+
+```python
+from matrx_content_guard import validate_content, apply_patch, SearchReplacePatch, SearchReplaceHunk
+
+report = validate_content("<script>alert(1)</script>", "html_page_document")
+report.blocked  # False — inline script is a supported feature; only genuinely dangerous constructs block.
+
+result = apply_patch(
+    "<h1>Hello</h1>",
+    SearchReplacePatch(hunks=[SearchReplaceHunk(search="Hello", replace="Hi")]),
+)
+result.result  # "<h1>Hi</h1>"
+```

matrx_content_guard-0.1.0/README.md

@@ -0,0 +1,23 @@
+# matrx-content-guard
+
+Deterministic HTML/CSS/JS content validation + patch/diff editing for the
+Matrx CMS agent-authoring layer. Pure Python, no DB access, no tool-framework
+imports — every agent mutation to `html_pages` / `client_*` content flows
+through this library before it's written.
+
+See `CONTRACT.md` for the full typed API and `FEATURE.md` for the durable
+design notes (parser choice, permissive-first policy rationale, byte-
+preservation guarantee).
+
+```python
+from matrx_content_guard import validate_content, apply_patch, SearchReplacePatch, SearchReplaceHunk
+
+report = validate_content("<script>alert(1)</script>", "html_page_document")
+report.blocked  # False — inline script is a supported feature; only genuinely dangerous constructs block.
+
+result = apply_patch(
+    "<h1>Hello</h1>",
+    SearchReplacePatch(hunks=[SearchReplaceHunk(search="Hello", replace="Hi")]),
+)
+result.result  # "<h1>Hi</h1>"
+```