faf-python-sdk 1.4.0__tar.gz → 2.0.0__tar.gz

{faf_python_sdk-1.4.0 → faf_python_sdk-2.0.0}/.github/workflows/pypi.yml

@@ -10,5 +10,13 @@ jobs:
       - uses: actions/setup-python@v5
         with:
           python-version: "3.11"
+      # Gate: the full suite, with the live faf-kernel oracle required, passes
+      # before anything is built or published.
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+      - run: npm install --prefix scripts
+      - run: pip install -e ".[dev]"
+      - run: FAF_REQUIRE_KERNEL=1 python -m pytest tests/ -q
       - run: pip install build && python -m build
       - uses: pypa/gh-action-pypi-publish@release/v1

{faf_python_sdk-1.4.0 → faf_python_sdk-2.0.0}/.github/workflows/testpypi.yml

@@ -1,13 +1,13 @@
 name: Publish to TestPyPI
 
-# Fires on every version tag push (e.g. `git push origin v0.1.5`).
-# Stage 1 of the publish flow: stage to TestPyPI for verification BEFORE
-# creating a GitHub Release (which then fires pypi.yml for production).
+# Fires on every version tag push. Stage with a pre-release tag (e.g.
+# `v2.1.0rc1` on a version-only commit), so the real version is never burned on
+# TestPyPI before review.
 #
-# Flow:
-#   1. git tag v0.1.5 && git push origin v0.1.5     → this workflow runs
-#   2. verify install from TestPyPI                  → manual / via verify_install.py
-#   3. gh release create v0.1.5                     → triggers pypi.yml (production)
+# Flow (/pubpypi):
+#   1. tag vX.Y.ZrcN + push                          → this workflow (TestPyPI)
+#   2. verify install from TestPyPI, independent review
+#   3. on GO: tag vX.Y.Z on main, then run pypi.yml (workflow_dispatch) from that tag
 
 on:
   push:

{faf_python_sdk-1.4.0 → faf_python_sdk-2.0.0}/.gitignore

@@ -42,3 +42,6 @@ htmlcov/
 # OS
 .DS_Store
 Thumbs.db
+
+# Node (kernel oracle for the parity harness)
+node_modules/

{faf_python_sdk-1.4.0 → faf_python_sdk-2.0.0}/CHANGELOG.md

@@ -3,6 +3,68 @@
 All notable changes to faf-python-sdk are documented here.
 Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
 
+## [2.0.0] - 2026-09-28 — The Always33 Edition
+
+One engine, one number: faf-python-sdk scores all 33 slots exactly like faf-kernel — the same score faf-cli 8, claude-faf-mcp 7, faf-mcp 4 and grok-faf-mcp 2 give.
+
+`score_faf(yaml)` returns what faf-kernel (Wolfe-Jam/faf-rust `crates/faf-kernel`,
+npm `faf-scoring-kernel@3.0.0`) returns, on every file. A parity harness
+(`tests/test_always33_parity.py`) checks score, tier, populated, empty, ignored,
+active, total and every slot state against the kernel's recorded answers: 845/845
+fixtures (58 real `project.faf` files from public Wolfe-Jam repos, 55 rule
+fixtures, 272 YAML-layer cases, 460 seeded fuzz documents).
+
+### Changed (breaking — scores move)
+- **Always 33 slots.** The 12 enterprise slots count unless the file marks them
+  `slotignored`; `slotignored` slots drop out of the denominator
+  (`active = 33 − ignored`). A file with the 21 base slots filled and no markers
+  scores 64% (21/33); the same file plus the 12 markers scores 100% (21/21).
+- `score_faf(yaml, tier=...)` still accepts `tier`, but it no longer changes the
+  slot count: `LicenseTier.BASE` and `LicenseTier.ENTERPRISE` give the same result.
+- `Mk4Result.slots` (and `to_dict()["slots"]`) always lists 33 slots, in kernel
+  order, under the kernel's canonical names: `stack.framework`, `stack.css`,
+  `stack.state`, `stack.api`, `stack.db`, `stack.pkg_manager` (were
+  `stack.frontend`, `stack.css_framework`, `stack.state_management`,
+  `stack.api_type`, `stack.database`, `stack.package_manager`). `Mk4Result` keeps
+  its fields.
+- `tbd` and `todo` (case-insensitive) are placeholders and score as empty, with
+  the existing list (`none`, `null`, `n/a`, `unknown`, `not applicable`, …).
+- Short keys are read: `stack.framework`, `css`, `state`, `api`, `db`,
+  `pkg_manager`. The legacy key is read only when the short key is empty.
+- Rounding is half away from zero, as the kernel does (1/8 = 12.5% → 13, where
+  Python's `round()` gave 12).
+- YAML is read the way the kernel reads it (serde_yaml_ng on libyaml), not with
+  `yaml.safe_load`: flow-style YAML, a leading BOM and tabs inside values parse
+  as they do in the kernel; `<<` is an ordinary key (no YAML 1.1 merge); a
+  redefined anchor name resolves the way the kernel resolves it (an alias
+  follows the kernel's anchor ids, so it can land on a later anchor); duplicate
+  keys, a second document, an empty `?` key inside `[...]` (`[?, a]`, `[?]`),
+  alias expansion past the kernel's repetition limit and nesting deeper than
+  128 are unreadable, and nesting past that limit (`[`/`{` or block) is rejected
+  in linear time; a local tag (`!x value`) scores the slot empty.
+- Unreadable YAML scores 0 with every slot empty. `score_faf` does not raise for
+  any `str` or `bytes` input.
+
+### Added
+- `faf_sdk.mk4.SLOTS` (the 33 slot paths, kernel order), `TOTAL_SLOTS`,
+  `LEGACY_ALIASES`.
+- Parity harness and fixtures under `tests/fixtures/`; the kernel oracle
+  (`scripts/kernel_oracle.js`, pinned in `scripts/package.json`) and
+  `scripts/record_kernel_expected.py`, which records the kernel's answers.
+
+### Upgrading
+- Files without the 12 enterprise markers score lower. `faf auto` (faf-cli)
+  writes the 12 markers; with them, a complete 21-slot file scores 100%.
+- Code that reads `result.slots` by name: use the canonical short names above.
+- YAML the kernel can't read now scores 0: a duplicate key (1.4.0 kept the last
+  value), a second document (`---`), an empty `?` key inside `[...]`, nesting
+  deeper than 128. `tbd` and `todo` now count as empty.
+- Rounding is half away from zero (12.5% → 13), as the kernel rounds.
+
+### Notes
+- `generate_agents_md` / `generate_gemini_md` remain deprecated aliases in 2.0.0.
+- `validate()`'s completeness score is unchanged; it is not the Mk4 score.
+
 ## [1.4.0] - 2026-09-08 — The Interop Edition
 
 The interop functions get their real names: `author_agents_md` / `author_gemini_md` are public, `render_*` is the impl, `generate_*` is deprecated (removed in 2.0).

{faf_python_sdk-1.4.0 → faf_python_sdk-2.0.0}/CLAUDE.md

@@ -1,5 +1,5 @@
 <!-- faf:start -->
-<!-- faf: faf-python-sdk | Python |  | Python SDK for parsing, validating, scoring, and authoring .faf project context — the Mk4 engine + interop generators other Python FAF tools build on -->
+<!-- faf: faf-python-sdk | Python | library | Python SDK for parsing, validating, scoring, and authoring .faf project context — the Mk4 engine + interop generators other Python FAF tools build on -->
 <!-- faf: claim=project.faf | family=FAF -->
 
 # CLAUDE.md — faf-python-sdk
@@ -29,5 +29,5 @@ Python SDK for parsing, validating, scoring, and authoring .faf project context
 
 ---
 
-*STATUS: BI-SYNC ACTIVE — 2026-09-07T02:08:39.970Z*
+*STATUS: SYNC ACTIVE — 2026-09-28T17:59:27.771Z*
 <!-- faf:end -->

{faf_python_sdk-1.4.0 → faf_python_sdk-2.0.0}/CONTRIBUTING.md

@@ -26,7 +26,8 @@ That's it. You're ready to run tests and ship a fix.
 Run the full check pass:
 
 ```bash
-pytest tests/ -v          # all tests must pass
+npm install --prefix scripts                   # the faf-kernel oracle (once)
+FAF_REQUIRE_KERNEL=1 pytest tests/ -v          # all tests must pass, incl. the live-kernel check
 mypy faf_sdk/             # strict typing — no untyped defs
 ```
 

{faf_python_sdk-1.4.0 → faf_python_sdk-2.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: faf-python-sdk
-Version: 1.4.0
+Version: 2.0.0
 Summary: Persistent project context for Python — parse, validate, and score `.faf` files. The foundation other Python FAF tools (gemini-faf-mcp, custom MCP servers, CI validators) build on. IANA-registered application/vnd.faf+yaml.
 Project-URL: Homepage, https://faf.one
 Project-URL: Documentation, https://github.com/Wolfe-Jam/faf-python-sdk
@@ -41,12 +41,25 @@ The foundation other Python FAF tools build on. If you're building MCP servers,
 [![FAF](https://mcpaas.live/badge/Wolfe-Jam/faf-python-sdk.svg)](https://builder.faf.one)
 [![PyPI](https://img.shields.io/pypi/v/faf-python-sdk?style=for-the-badge&logo=pypi&logoColor=white)](https://pypi.org/project/faf-python-sdk/)
 [![Downloads](https://img.shields.io/pypi/dm/faf-python-sdk?style=for-the-badge&color=blue)](https://pypi.org/project/faf-python-sdk/)
-[![Tests](https://img.shields.io/badge/tests-216%20passing-brightgreen?style=for-the-badge)](https://github.com/Wolfe-Jam/faf-python-sdk)
+[![Tests](https://img.shields.io/badge/tests-1070%20passing-brightgreen?style=for-the-badge)](https://github.com/Wolfe-Jam/faf-python-sdk)
 [![IANA](https://img.shields.io/badge/IANA-registered-informational?style=for-the-badge)](https://www.iana.org/assignments/media-types/application/vnd.faf+yaml)
 
 **Media Type:** `application/vnd.faf+yaml` (IANA registered)
 
-## What's New in v1.4.0 — The Interop Edition
+## What's New in v2.0.0 — The Always33 Edition
+
+One engine, one number: faf-python-sdk scores all 33 slots exactly like faf-kernel — the same score faf-cli 8, claude-faf-mcp 7, faf-mcp 4 and grok-faf-mcp 2 give.
+
+- **Always 33 slots.** The 12 enterprise slots count unless marked `slotignored`. 21 base slots filled with no markers: 64% (21/33). The same file plus the 12 markers: 100% (21/21). `faf auto` (faf-cli) writes the markers.
+- `tbd` / `todo` are placeholders; short keys (`framework`, `css`, `state`, `api`, `db`, `pkg_manager`) are read.
+- YAML is read the way the kernel reads it; unreadable YAML scores 0 without raising.
+- `score_faf(yaml, tier=...)` still accepts `tier`; it no longer changes the slot count.
+- **Upgrading:** `result.slots` lists all 33 slots under the kernel's names (`stack.framework`, `css`, `state`, `api`, `db`, `pkg_manager`; were `frontend`, `css_framework`, `state_management`, `api_type`, `database`, `package_manager`). Code that reads slots by name needs the new names. YAML the kernel can't read now scores 0 (a duplicate key, a second document, nesting deeper than 128), and rounding is half away from zero (12.5% → 13), as the kernel does.
+- Parity harness: 845/845 fixtures match faf-kernel (`faf-scoring-kernel@3.0.0`), including the `project.faf` of 58 public repos.
+
+See [CHANGELOG.md](CHANGELOG.md) for the full list of changes.
+
+## v1.4.0 — The Interop Edition
 
 The interop functions get their real names: `author_agents_md` / `author_gemini_md` are public, `render_*` is the impl, `generate_*` is deprecated (removed in 2.0).
 
@@ -63,7 +76,7 @@ print(author_agents_md(faf.data.raw))   # takes the raw dict — carries top-lev
 
 Any Python FAF tool that authors an AI-context file wraps this now — never hand-roll one. `gemini-faf-mcp` 2.7.0's `faf_agents` / `faf_gemini` are the reference wrappers.
 
-## What's New in v1.2.0 — The Dart Edition
+## v1.2.0 — The Dart Edition
 
 Adds `detect_dart_project()`: content-aware Dart/Flutter detection from a `pubspec.yaml` (Flutter app vs package · Dart MCP / backend / CLI / library), reproducing faf-cli's engine byte-for-byte — 20 shared fixtures, parity-tested.
 
@@ -74,7 +87,7 @@ d = detect_dart_project(".")
 print(d.app_type, d.framework)   # e.g. "mobile" "Flutter"
 ```
 
-## What's New in v1.1.0
+## v1.1.0
 
 **Mk4 Championship Scoring Engine** — the same 33-slot scoring algorithm used by the Rust compiler and TypeScript CLI, now in Python. Same slots, same formula, same scores. Every FAF tool in every language now agrees on what 100% means.
 
@@ -114,26 +127,24 @@ print(f"Slots: {result.populated}/{result.total} populated")
 
 ## Mk4 Scoring
 
-The Mk4 engine scores `.faf` files by checking 21 universal slots (project metadata, human context, tech stack). Each slot is **Populated**, **Empty**, or **Slotignored**. The score is the percentage of active slots that are populated.
+The Mk4 engine scores `.faf` files against 33 slots (project metadata, human context, tech stack, and 12 enterprise slots), exactly as faf-kernel does. Each slot is **Populated**, **Empty**, or **Slotignored**. The score is populated ÷ active, where active = 33 − slotignored.
 
 ```python
-from faf_sdk import score_faf, LicenseTier
+from faf_sdk import score_faf
 
-# Base scoring (21 slots)
 result = score_faf(yaml_content)
 print(result.score)      # 0-100
-print(result.tier)       # Trophy/Gold/Silver/Bronze/Green/Yellow/Red
+print(result.tier)       # TROPHY / GOLD / SILVER / BRONZE / GREEN / YELLOW / RED / WHITE
 print(result.populated)  # slots with real data
-print(result.active)     # total minus slotignored
-print(result.slots)      # per-slot breakdown
-
-# Enterprise scoring (33 slots — adds monorepo/infra)
-result = score_faf(yaml_content, LicenseTier.ENTERPRISE)
+print(result.active)     # 33 minus slotignored
+print(result.slots)      # per-slot breakdown, 33 entries in kernel order
 ```
 
-**Placeholder rejection:** Values like `"null"`, `"unknown"`, `"n/a"`, `"Describe your project goal"` are detected and scored as Empty — not Populated.
+**Placeholder rejection:** Values like `"null"`, `"none"`, `"unknown"`, `"n/a"`, `"tbd"`, `"todo"`, `"Describe your project goal"` (case-insensitive) are scored as Empty — not Populated.
+
+**Slotignored:** Set any slot to `slotignored` to exclude it from scoring. A project that does not use the 12 enterprise slots marks them `slotignored` (`faf auto` writes them) and can still reach 100%.
 
-**Slotignored:** Set any slot to `slotignored` to exclude it from scoring. A backend-only project can mark `frontend: slotignored` and still reach 100%.
+**Short keys:** `stack.framework`, `css`, `state`, `api`, `db`, `pkg_manager` are the canonical names; the legacy `frontend`, `css_framework`, `state_management`, `api_type`, `database`, `package_manager` are read when the short key is empty.
 
 ## Parsing
 
@@ -188,7 +199,7 @@ root = find_project_root()
 
 | Function | Returns | Description |
 |----------|---------|-------------|
-| `score_faf(yaml, tier?)` | `Mk4Result` | Mk4 score (21 or 33 slots) |
+| `score_faf(yaml)` | `Mk4Result` | Mk4 score, always 33 slots (faf-kernel parity) |
 | `parse(content)` | `FafFile` | Parse YAML string |
 | `parse_file(path)` | `FafFile` | Parse from file path |
 | `validate(faf)` | `ValidationResult` | Structure validation + warnings |

{faf_python_sdk-1.4.0 → faf_python_sdk-2.0.0}/README.md

@@ -9,12 +9,25 @@ The foundation other Python FAF tools build on. If you're building MCP servers,
 [![FAF](https://mcpaas.live/badge/Wolfe-Jam/faf-python-sdk.svg)](https://builder.faf.one)
 [![PyPI](https://img.shields.io/pypi/v/faf-python-sdk?style=for-the-badge&logo=pypi&logoColor=white)](https://pypi.org/project/faf-python-sdk/)
 [![Downloads](https://img.shields.io/pypi/dm/faf-python-sdk?style=for-the-badge&color=blue)](https://pypi.org/project/faf-python-sdk/)
-[![Tests](https://img.shields.io/badge/tests-216%20passing-brightgreen?style=for-the-badge)](https://github.com/Wolfe-Jam/faf-python-sdk)
+[![Tests](https://img.shields.io/badge/tests-1070%20passing-brightgreen?style=for-the-badge)](https://github.com/Wolfe-Jam/faf-python-sdk)
 [![IANA](https://img.shields.io/badge/IANA-registered-informational?style=for-the-badge)](https://www.iana.org/assignments/media-types/application/vnd.faf+yaml)
 
 **Media Type:** `application/vnd.faf+yaml` (IANA registered)
 
-## What's New in v1.4.0 — The Interop Edition
+## What's New in v2.0.0 — The Always33 Edition
+
+One engine, one number: faf-python-sdk scores all 33 slots exactly like faf-kernel — the same score faf-cli 8, claude-faf-mcp 7, faf-mcp 4 and grok-faf-mcp 2 give.
+
+- **Always 33 slots.** The 12 enterprise slots count unless marked `slotignored`. 21 base slots filled with no markers: 64% (21/33). The same file plus the 12 markers: 100% (21/21). `faf auto` (faf-cli) writes the markers.
+- `tbd` / `todo` are placeholders; short keys (`framework`, `css`, `state`, `api`, `db`, `pkg_manager`) are read.
+- YAML is read the way the kernel reads it; unreadable YAML scores 0 without raising.
+- `score_faf(yaml, tier=...)` still accepts `tier`; it no longer changes the slot count.
+- **Upgrading:** `result.slots` lists all 33 slots under the kernel's names (`stack.framework`, `css`, `state`, `api`, `db`, `pkg_manager`; were `frontend`, `css_framework`, `state_management`, `api_type`, `database`, `package_manager`). Code that reads slots by name needs the new names. YAML the kernel can't read now scores 0 (a duplicate key, a second document, nesting deeper than 128), and rounding is half away from zero (12.5% → 13), as the kernel does.
+- Parity harness: 845/845 fixtures match faf-kernel (`faf-scoring-kernel@3.0.0`), including the `project.faf` of 58 public repos.
+
+See [CHANGELOG.md](CHANGELOG.md) for the full list of changes.
+
+## v1.4.0 — The Interop Edition
 
 The interop functions get their real names: `author_agents_md` / `author_gemini_md` are public, `render_*` is the impl, `generate_*` is deprecated (removed in 2.0).
 
@@ -31,7 +44,7 @@ print(author_agents_md(faf.data.raw))   # takes the raw dict — carries top-lev
 
 Any Python FAF tool that authors an AI-context file wraps this now — never hand-roll one. `gemini-faf-mcp` 2.7.0's `faf_agents` / `faf_gemini` are the reference wrappers.
 
-## What's New in v1.2.0 — The Dart Edition
+## v1.2.0 — The Dart Edition
 
 Adds `detect_dart_project()`: content-aware Dart/Flutter detection from a `pubspec.yaml` (Flutter app vs package · Dart MCP / backend / CLI / library), reproducing faf-cli's engine byte-for-byte — 20 shared fixtures, parity-tested.
 
@@ -42,7 +55,7 @@ d = detect_dart_project(".")
 print(d.app_type, d.framework)   # e.g. "mobile" "Flutter"
 ```
 
-## What's New in v1.1.0
+## v1.1.0
 
 **Mk4 Championship Scoring Engine** — the same 33-slot scoring algorithm used by the Rust compiler and TypeScript CLI, now in Python. Same slots, same formula, same scores. Every FAF tool in every language now agrees on what 100% means.
 
@@ -82,26 +95,24 @@ print(f"Slots: {result.populated}/{result.total} populated")
 
 ## Mk4 Scoring
 
-The Mk4 engine scores `.faf` files by checking 21 universal slots (project metadata, human context, tech stack). Each slot is **Populated**, **Empty**, or **Slotignored**. The score is the percentage of active slots that are populated.
+The Mk4 engine scores `.faf` files against 33 slots (project metadata, human context, tech stack, and 12 enterprise slots), exactly as faf-kernel does. Each slot is **Populated**, **Empty**, or **Slotignored**. The score is populated ÷ active, where active = 33 − slotignored.
 
 ```python
-from faf_sdk import score_faf, LicenseTier
+from faf_sdk import score_faf
 
-# Base scoring (21 slots)
 result = score_faf(yaml_content)
 print(result.score)      # 0-100
-print(result.tier)       # Trophy/Gold/Silver/Bronze/Green/Yellow/Red
+print(result.tier)       # TROPHY / GOLD / SILVER / BRONZE / GREEN / YELLOW / RED / WHITE
 print(result.populated)  # slots with real data
-print(result.active)     # total minus slotignored
-print(result.slots)      # per-slot breakdown
-
-# Enterprise scoring (33 slots — adds monorepo/infra)
-result = score_faf(yaml_content, LicenseTier.ENTERPRISE)
+print(result.active)     # 33 minus slotignored
+print(result.slots)      # per-slot breakdown, 33 entries in kernel order
 ```
 
-**Placeholder rejection:** Values like `"null"`, `"unknown"`, `"n/a"`, `"Describe your project goal"` are detected and scored as Empty — not Populated.
+**Placeholder rejection:** Values like `"null"`, `"none"`, `"unknown"`, `"n/a"`, `"tbd"`, `"todo"`, `"Describe your project goal"` (case-insensitive) are scored as Empty — not Populated.
+
+**Slotignored:** Set any slot to `slotignored` to exclude it from scoring. A project that does not use the 12 enterprise slots marks them `slotignored` (`faf auto` writes them) and can still reach 100%.
 
-**Slotignored:** Set any slot to `slotignored` to exclude it from scoring. A backend-only project can mark `frontend: slotignored` and still reach 100%.
+**Short keys:** `stack.framework`, `css`, `state`, `api`, `db`, `pkg_manager` are the canonical names; the legacy `frontend`, `css_framework`, `state_management`, `api_type`, `database`, `package_manager` are read when the short key is empty.
 
 ## Parsing
 
@@ -156,7 +167,7 @@ root = find_project_root()
 
 | Function | Returns | Description |
 |----------|---------|-------------|
-| `score_faf(yaml, tier?)` | `Mk4Result` | Mk4 score (21 or 33 slots) |
+| `score_faf(yaml)` | `Mk4Result` | Mk4 score, always 33 slots (faf-kernel parity) |
 | `parse(content)` | `FafFile` | Parse YAML string |
 | `parse_file(path)` | `FafFile` | Parse from file path |
 | `validate(faf)` | `ValidationResult` | Structure validation + warnings |

{faf_python_sdk-1.4.0 → faf_python_sdk-2.0.0}/faf_sdk/__init__.py

@@ -30,8 +30,8 @@ from .interop import (
     author_gemini_md,
     render_agents_md,
     render_gemini_md,
-    generate_agents_md,  # deprecated alias — removed in 2.0
-    generate_gemini_md,  # deprecated alias — removed in 2.0
+    generate_agents_md,  # deprecated alias — kept in 2.0, removal planned
+    generate_gemini_md,  # deprecated alias — kept in 2.0, removal planned
     faf_meta_tag,
 )
 from .types import (
@@ -44,7 +44,7 @@ from .types import (
     AIScoring
 )
 
-__version__ = "1.4.0"
+__version__ = "2.0.0"
 __all__ = [
     # Parser
     "parse",