fancy-fine-print 0.1.0__tar.gz

fancy_fine_print-0.1.0/.gitattributes

@@ -0,0 +1,10 @@
+# Line endings are pinned, not left to a clone's core.autocrlf: the writer is
+# compared byte for byte with the PHP reference, and a source file checked out
+# with CRLF changes the bytes of any multi-line literal in it.
+* text=auto eol=lf
+
+*.pdf binary
+*.png binary
+*.jpg binary
+*.ttf binary
+*.gz  binary

fancy_fine_print-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,143 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+# Least-privilege: CI only reads the repo.
+permissions:
+  contents: read
+
+jobs:
+  test:
+    # Linux AND Windows: CPython on Windows ships zlib-ng, the reason the
+    # canon tier is mandatory (plan section 5, Python traps).
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v7
+
+      # Third-party dependency allowlist. Cheap, and failing here is cheap --
+      # the same check gates the release, so a PR that adds an unapproved or
+      # abandoned dependency finds out now rather than at tag time.
+      # The allowlist is FETCHED, never vendored: one source, no copies to drift.
+      - name: Fetch the third-party allowlist
+        uses: actions/checkout@v7
+        with:
+          repository: Particle-Academy/.github
+          ref: 1a1fad08a5fa685d5aca89e4bfa0b6afac7fa949
+          path: .third-party-allowlist
+          persist-credentials: false
+
+      - name: Verify the pinned checkout
+        # Generated by pin-github-checks.mjs -- edit the pin with that tool, not by
+        # hand. The ref above is a commit SHA, and every file the fetched code reads
+        # is hashed here, so a push to the source repo cannot change what runs in
+        # this workflow until someone reviews it and re-pins. It runs from the
+        # workspace with nothing preloaded, so neither the job's working-directory
+        # nor a variable an earlier step left behind decides what it reads or runs.
+        shell: bash
+        working-directory: ${{ github.workspace }}
+        env:
+          NODE_OPTIONS: ''
+          NODE_PATH: ''
+          BASH_ENV: ''
+          ENV: ''
+          SHELLOPTS: ''
+          BASHOPTS: ''
+          LD_PRELOAD: ''
+          LD_LIBRARY_PATH: ''
+          LD_AUDIT: ''
+          DYLD_INSERT_LIBRARIES: ''
+          DYLD_LIBRARY_PATH: ''
+          PIN_ROOT: .third-party-allowlist
+          PIN_DIR: .third-party-allowlist/third-party
+          PIN_SHA: 1a1fad08a5fa685d5aca89e4bfa0b6afac7fa949
+          PIN_SHA256: |
+            4b94acfac87136b0942123b9f227919d7e2e3d67863bcdceba32c9a73f765db0  check.mjs
+            1547306d567749d7410040cae2bfb9a648902de95c3378f6c5af54245c896e11  gate-graph.mjs
+            e5c6f925b2d5cab9e7bca220e8ad4d6bed809f5e2ab73cbefa9bb16d60bd2a86  allowlist.json
+        run: |
+          node -e '
+          const fs = require("node:fs");
+          const crypto = require("node:crypto");
+          const { execFileSync } = require("node:child_process");
+          const env = process.env;
+          const fail = [];
+          const head = execFileSync("git", ["-C", env.PIN_ROOT, "rev-parse", "HEAD"], { encoding: "utf8" }).trim();
+          if (head !== env.PIN_SHA) fail.push("checkout is at " + head + ", pinned " + env.PIN_SHA);
+          const want = env.PIN_SHA256.split(String.fromCharCode(10)).map((l) => l.trim()).filter(Boolean);
+          if (!want.length) fail.push("no file hashes are pinned");
+          for (const entry of want) {
+            const [hash, ...rest] = entry.split(" ").filter(Boolean);
+            const file = rest.join(" ");
+            let got = "missing";
+            try {
+              const text = fs.readFileSync(env.PIN_DIR + "/" + file, "latin1");
+              const lf = text.split(String.fromCharCode(13, 10)).join(String.fromCharCode(10));
+              got = crypto.createHash("sha256").update(lf, "latin1").digest("hex");
+            } catch {}
+            if (got !== hash) fail.push(file + " sha256 is " + got + ", pinned " + hash);
+          }
+          for (const f of fail) console.log("::error::Pinned checkout mismatch: " + f);
+          if (fail.length) {
+            console.log("::error::Refusing to run fetched code that does not match its pin. Review the upstream change, then re-pin with pin-github-checks.mjs.");
+            process.exit(1);
+          }
+          console.log("Pinned checkout verified: " + head + ", " + want.length + " files match.");
+          '
+
+      - name: Third-party dependency allowlist
+        run: |
+          node .third-party-allowlist/third-party/check.mjs --repo .
+          # Delete it. A fetched checkout left lying in the workspace is not
+          # inert: vitest globbed the checker's own tests out of it and failed
+          # a package whose code was fine. Removed with node, not rm -rf,
+          # because some of these matrices run on windows-latest where a
+          # multi-line run: block is PowerShell and rm -rf is not a command.
+          node -e "require('node:fs').rmSync('.third-party-allowlist',{recursive:true,force:true})"
+
+      - uses: actions/setup-python@v7
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      # PHP is REQUIRED, not optional. tests/test_parity_php.py is the
+      # cross-runtime reader guarantee and it FAILS when php is absent rather
+      # than skipping - a skip here is a green build with zero parity coverage,
+      # which is exactly how two suites in this org reported success over
+      # nothing for months.
+      - uses: shivammathur/setup-php@v2
+        with:
+          php-version: "8.4"
+          coverage: none
+          extensions: mbstring, zip
+        env:
+          update: true # latest patch, not the runner's preinstalled one
+      - name: Floor PHP at the PHP2Shell-patched release (CVE-2026-109618/109619)
+        shell: bash
+        run: php -r '$v=$argv[1]??PHP_MAJOR_VERSION.".".PHP_MINOR_VERSION.".".PHP_RELEASE_VERSION; $f=["8.5"=>"8.5.12","8.4"=>"8.4.27","8.3"=>"8.3.36","8.2"=>"8.2.35"][implode(".",array_slice(explode(".",$v),0,2))]??(version_compare($v,"8.6",">=")?"8.6":"8.2.35"); if(version_compare($v,$f,"<")){echo "::error::PHP $v is below the PHP2Shell floor $f".PHP_EOL;exit(1);} echo "PHP $v >= PHP2Shell floor $f".PHP_EOL;'
+
+      # The PHP reference, PINNED to the release this port reproduces. A test
+      # asserts the checkout's Agent::VERSION equals PHP_REFERENCE.
+      - name: Check out the PHP fine-print (pinned)
+        uses: actions/checkout@v7
+        with:
+          repository: Particle-Academy/fine-print
+          ref: v0.7.0
+          path: .php-fine-print
+          persist-credentials: false
+
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Test
+        run: python -m pytest
+        env:
+          FINE_PRINT_PHP_SRC: ${{ github.workspace }}/.php-fine-print/src

fancy_fine_print-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,225 @@
+name: Publish
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions: {}
+
+jobs:
+  guard:
+    # Generated by pin-github-checks.mjs. Code fetched from another repo runs
+    # HERE, in a job holding nothing but `contents: read` -- never in a job that
+    # can publish or write. build needs this job, so it still cannot start
+    # until the check has passed.
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+
+      # Release gate: third-party dependencies must be approved and still
+      # maintained BEFORE the tarball reaches the registry. Once it is
+      # published, an unapproved or abandoned dependency has already shipped
+      # to everyone who upgrades -- the same reason the changelog gate sits
+      # here. The allowlist is FETCHED, never vendored: one source of truth,
+      # so there is no per-repo copy that can drift out of agreement with it.
+      - name: Fetch the third-party allowlist
+        uses: actions/checkout@v7
+        with:
+          repository: Particle-Academy/.github
+          ref: 1a1fad08a5fa685d5aca89e4bfa0b6afac7fa949
+          path: .third-party-allowlist
+          persist-credentials: false
+
+      - name: Verify the pinned checkout
+        # Generated by pin-github-checks.mjs -- edit the pin with that tool, not by
+        # hand. The ref above is a commit SHA, and every file the fetched code reads
+        # is hashed here, so a push to the source repo cannot change what runs in
+        # this workflow until someone reviews it and re-pins. It runs from the
+        # workspace with nothing preloaded, so neither the job's working-directory
+        # nor a variable an earlier step left behind decides what it reads or runs.
+        shell: bash
+        working-directory: ${{ github.workspace }}
+        env:
+          NODE_OPTIONS: ''
+          NODE_PATH: ''
+          BASH_ENV: ''
+          ENV: ''
+          SHELLOPTS: ''
+          BASHOPTS: ''
+          LD_PRELOAD: ''
+          LD_LIBRARY_PATH: ''
+          LD_AUDIT: ''
+          DYLD_INSERT_LIBRARIES: ''
+          DYLD_LIBRARY_PATH: ''
+          PIN_ROOT: .third-party-allowlist
+          PIN_DIR: .third-party-allowlist/third-party
+          PIN_SHA: 1a1fad08a5fa685d5aca89e4bfa0b6afac7fa949
+          PIN_SHA256: |
+            4b94acfac87136b0942123b9f227919d7e2e3d67863bcdceba32c9a73f765db0  check.mjs
+            1547306d567749d7410040cae2bfb9a648902de95c3378f6c5af54245c896e11  gate-graph.mjs
+            e5c6f925b2d5cab9e7bca220e8ad4d6bed809f5e2ab73cbefa9bb16d60bd2a86  allowlist.json
+        run: |
+          node -e '
+          const fs = require("node:fs");
+          const crypto = require("node:crypto");
+          const { execFileSync } = require("node:child_process");
+          const env = process.env;
+          const fail = [];
+          const head = execFileSync("git", ["-C", env.PIN_ROOT, "rev-parse", "HEAD"], { encoding: "utf8" }).trim();
+          if (head !== env.PIN_SHA) fail.push("checkout is at " + head + ", pinned " + env.PIN_SHA);
+          const want = env.PIN_SHA256.split(String.fromCharCode(10)).map((l) => l.trim()).filter(Boolean);
+          if (!want.length) fail.push("no file hashes are pinned");
+          for (const entry of want) {
+            const [hash, ...rest] = entry.split(" ").filter(Boolean);
+            const file = rest.join(" ");
+            let got = "missing";
+            try {
+              const text = fs.readFileSync(env.PIN_DIR + "/" + file, "latin1");
+              const lf = text.split(String.fromCharCode(13, 10)).join(String.fromCharCode(10));
+              got = crypto.createHash("sha256").update(lf, "latin1").digest("hex");
+            } catch {}
+            if (got !== hash) fail.push(file + " sha256 is " + got + ", pinned " + hash);
+          }
+          for (const f of fail) console.log("::error::Pinned checkout mismatch: " + f);
+          if (fail.length) {
+            console.log("::error::Refusing to run fetched code that does not match its pin. Review the upstream change, then re-pin with pin-github-checks.mjs.");
+            process.exit(1);
+          }
+          console.log("Pinned checkout verified: " + head + ", " + want.length + " files match.");
+          '
+
+      - name: Third-party dependency allowlist
+        run: |
+          node .third-party-allowlist/third-party/check.mjs --repo .
+          # Delete it. A fetched checkout left lying in the workspace is not
+          # inert: vitest globbed the checker's own tests out of it and failed
+          # a package whose code was fine. Removed with node, not rm -rf,
+          # because some of these matrices run on windows-latest where a
+          # multi-line run: block is PowerShell and rm -rf is not a command.
+          node -e "require('node:fs').rmSync('.third-party-allowlist',{recursive:true,force:true})"
+
+  # Build and publish are separate jobs so `id-token: write` is never held by
+  # the job that executes build code.
+  build:
+    needs: guard
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.x"
+
+      # The one documentation failure that cannot be repaired later: once the
+      # sdist is on PyPI, whoever upgraded into it has no way to learn what
+      # changed. Checked before anything is built.
+      - name: Require a CHANGELOG entry for this tag
+        run: |
+          version="${GITHUB_REF_NAME#v}"
+          grep -q "^## \[${version}\]" CHANGELOG.md || {
+            echo "::error::No CHANGELOG.md entry for ${version}."
+            exit 1
+          }
+
+          # ORDER, not just presence. The check above asks only whether a
+          # heading exists SOMEWHERE. fancy-flow's changelog had four sections
+          # inserted ABOVE the [Unreleased] marker, so everything appended
+          # since -- including 0.49.0 -- landed below them, and reading
+          # top-down showed 0.48.1 as newest. That PASSED the presence check.
+          #
+          # A consumer deciding whether to upgrade reads top-down. Complete but
+          # mis-ordered is a truthful-looking lie, and it is invisible to
+          # whoever wrote it, because they are looking at their own entry
+          # rather than at the file.
+          first=$(grep -E '^## ' CHANGELOG.md \
+            | grep -viE '^## +\[?unreleased\]?' \
+            | head -1)
+
+          if ! printf '%s' "$first" | grep -qE "^## +\[?v?${version}\]?"; then
+            echo "::error::CHANGELOG.md has an entry for ${version}, but it is NOT the first version heading."
+            echo "::error::Top of file is: ${first}"
+            echo "::error::Move this release above the older entries, then re-tag."
+            exit 1
+          fi
+
+      - name: Require the version to match the tag
+        run: |
+          version="${GITHUB_REF_NAME#v}"
+          grep -q "^version = \"${version}\"$" pyproject.toml || {
+            echo "pyproject.toml version does not match tag ${GITHUB_REF_NAME}."
+            exit 1
+          }
+
+      - run: python -m pip install --upgrade build && python -m build
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dists
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/fancy-fine-print
+    permissions:
+      id-token: write        # mandatory for Trusted Publishing
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dists
+          path: dist/
+      # Pinned by SHA, not by tag: a mutable reference in exactly this position
+      # is what the April 2026 supply-chain compromises exploited.
+      # v1.14.2 -- no `password:` (that is the point) and attestations default
+      # to true.
+      - uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33
+
+  # The GitHub release is its OWN job, deliberately the third one.
+  #
+  # This repo already splits `build` from `publish` so that `id-token: write`
+  # is never held by the job executing package code. Adding `contents: write`
+  # to either would undo that reasoning from the other side: in `build` it
+  # hands repo-write to code that runs during the build, and in `publish` it
+  # widens the single job holding the Trusted Publishing credential. So the
+  # job that can write to the repo runs no build code and holds no token.
+  #
+  # Needed because every Python repo in this estate had ZERO GitHub releases
+  # while the npm and PHP repos publish one per tag -- the same "a fix applied
+  # only where the problem was noticed" gap, one ecosystem further along.
+  #
+  # Notes come from CHANGELOG.md so there is no second description to drift.
+  release:
+    needs: publish
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+
+      - name: Publish the GitHub release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          VERSION="${GITHUB_REF_NAME#v}"
+
+          if gh release view "$GITHUB_REF_NAME" >/dev/null 2>&1; then
+            echo "Release $GITHUB_REF_NAME already exists; leaving it alone."
+            exit 0
+          fi
+
+          # The section for this version, up to the next `## ` heading.
+          awk -v v="$VERSION" '
+            /^## / { if (found) exit; if (index($0, v)) { found = 1 }; next }
+            found { print }
+          ' CHANGELOG.md > notes.md
+
+          gh release create "$GITHUB_REF_NAME" --title "$GITHUB_REF_NAME" --notes-file notes.md
+          echo "Published release $GITHUB_REF_NAME."

fancy_fine_print-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+build/
+dist/
+*.egg-info/
+.venv/
+venv/
+.coverage
+htmlcov/
+.DS_Store

fancy_fine_print-0.1.0/AGENTS.md

@@ -0,0 +1,122 @@
+# AGENTS.md — fine-print-py
+
+This file describes **this repository's code**: what it is, the invariants it
+must keep, and the traps in porting to it. Process rules (publishing, version
+policy, backports) live in the envelope's `RULES.md` and are never copied here.
+
+## What this is
+
+`fancy-fine-print` (import `fine_print`): the Python port of PHP
+`particle-academy/fine-print`. **Its reader is a port of fine-print 0.7.0's**
+(`PHP_REFERENCE` in `src/fine_print/__init__.py`), and parity is a test
+result, not a claim: `tests/test_parity_php.py` runs PHP and this port over
+the harvested corpus and requires equal results.
+
+**Status: 0.1.0, the READER only** (owner, 2026-11-07, council CC-fancy-0010:
+"we need a python fine print, not force them to use php"; the first consumer
+is LiftPoint's Python engine, which replaces pdfplumber's `extract_words`).
+This reverses the plan's writer-first order. The writer (phase W), the
+renderer (X1 to X4) and page serving (S) are still to come; the plan is the
+envelope's `.ai/plans/fine-print-ports.md`. The writer conformance rows below
+(`writer-model`, `writer-bytes`) are not run yet: there is no writer to run.
+
+## The reader (0.1.0)
+
+Module map, each mirroring a PHP class: `parser` (Parser, ITERATIVE),
+`filters` (Filters), `limits` (Limits, Budget), `document` (Document),
+`agent` (Agent's read half), `text/` (Encodings from generated tables, CMap,
+Font, TextExtractor as `extractor`, Layout, Words, TextString), `security/`
+(AgentReadGuard as `guard`, InstructionPatterns, ActiveContentScanner as
+`active`, StandardSecurity as `standard`), `crypto/` (Aes, Rc4), `_php`
+(every PHP behaviour reproduced, each probed against PHP 8.4).
+
+- **Offsets are characters, PHP's are bytes.** Every text in the reader is
+  valid UTF-8 (mbstring-scrubbed), so a byte offset in PHP and a character
+  offset here name the same place, and the reports PHP converts to characters
+  come out equal. Do not mix the two: spans, word ranges and guard ranges are
+  all characters.
+- **Names and keys are Latin-1 `str`**; turn one into report text with
+  `objects.name_text` (UTF-8, scrubbed), as PHP's json output of raw bytes.
+- **`??` is not `or`.** PHP's null-coalescing keeps `''` and `0`; use an
+  explicit `is None` (`extractor._arg`). `min`/`max` are `_php.pmin`/`pmax`
+  (PHP's NAN behaviour), comparisons are `_php.cmp`.
+- **Memory is accounted (D7).** `Budget.hold()`: content as it is joined,
+  cached objects, runs (`RUN_COST`), pieces (`PIECE_COST`), words
+  (`WORD_COST`); `Document.page_text` and friends restore the account on
+  return; `agent.read` keeps it for the whole read, as PHP's growth does.
+  Adding a structure that a file can grow means holding it.
+- **The corpus is harvested, never built here.** `scripts/harvest_php_corpus.php`
+  records every `Document::open` PHP's suite makes. Re-harvest when the PHP
+  reference moves, and update `PHP_REFERENCE`, the CI pin and
+  `tests/oracle/heavy.json` with it.
+- **`scripts/gen_encodings.php` generates `text/_encoding_data.py`.** Never
+  retype a table.
+
+- **Zero runtime dependencies.** The standard library only: `bytes`,
+  `bytearray`, `memoryview`, `struct`, `zlib`, `hashlib` (md5 with
+  `usedforsecurity=False`). `zlib.decompressobj().decompress(chunk,
+  max_length)` mirrors PHP's 4 KB bomb judgement exactly. **Our own AES: the
+  standard library has none**, plus RC4. Never the `cp1252`/`mac_roman`
+  codecs: they are not PDF WinAnsi/MacRoman. Anything third-party (numpy
+  included) is an approval request to the owner.
+- **Never regenerate a conformance row.** The bytes are the contract. If a row
+  looks wrong, the PHP reference is wrong or the port is; raise it, and the fix
+  lands in PHP and is re-exported.
+- **The PHP oracle is required.** CI checks out PHP fine-print at the pinned
+  tag (`FINE_PRINT_PHP_SRC`), and a missing PHP fails the run (D12).
+
+## The contract
+
+| suite | what it pins |
+|---|---|
+| `fine-print/php-semantics` | the PHP behaviours a `php` helper module must reproduce: `%.4F` ties (half-to-even on exact ties), `round()` pre-rounding, `number_format`, mbstring `?` substitution, WinAnsi by table |
+| `fine-print/writer-model` | validate, validateAndRepair, fromArray, describe, lint, jsonSchema, guide |
+| `fine-print/writer-bytes` | the PDF: raw byte identity, or identity after `canon()` |
+
+Normative text: fancy-conformance `suites/fine-print/SPEC.md` (file
+references, `canon()`, tiers, the PHP empty-object rule, pixel tolerances).
+
+## Invariants (restated from PHP; every one is enforced by rows)
+
+1. `Agent` is the only agent surface; `Document` is the host's raw view.
+2. Nothing executes, follows or fetches: no network or process API in `src`
+   (a source-grep test will enforce it).
+3. No attacker text in reports by default; scripts by length + SHA-256;
+   excerpts only on request.
+4. Names are compared decoded (`#xx`).
+5. Every loop a file can lengthen is bounded, in the same change as the loop.
+6. Refusals use the 12 REASONS, never a crash, hang or partial result. One
+   refusal exception type.
+7. Text streams through generators and never materialises.
+8. Decompression is judged while it runs, in 4 KB chunks.
+9. The extractor keeps hidden text; only the guard removes it.
+10. Encryption: the empty password only; `secure()` before any resolve; never
+    report key, O or U; our own RC4/AES.
+11. Writer: nothing active is emitted; links are checked twice; model text is
+    hex-only; names are sanitised; output is deterministic; images are bounded.
+12. Renderer: pixels judged before allocating; operators counted; form depth
+    and `q` stack capped; its own budget; everything undrawn reported.
+13. Per-edge work is bounded by the canvas (`MAX_SEGMENTS`, `MAX_DASHES`,
+    INF/NAN to 0).
+14. Font cache and glyph limits; hinting is never executed.
+15. Image bounds are checked before decoding; JPEG planes are checked.
+16. Group/mask buffers are cropped before allocation.
+17. Serving: authorise before the cache; never open client paths; checksummed
+    packets, no `pickle`; the watermark fails closed.
+
+## Python traps (plan section 5)
+
+- **Recursion and escapes.** The recursion limit is 1000, so the parser is
+  iterative. `RecursionError`, `MemoryError` and `OverflowError` must never
+  escape `Agent`.
+- **Bytes.** `b[i]` is an int and raises past the end, so forgiving-read
+  helpers reproduce PHP; use `bytearray`/`memoryview`, never `list[int]`.
+- **Arithmetic.** `%` and `//` floor while PHP truncates; `round` is
+  half-to-even; `bool` is an int; ints are unbounded while PHP overflows to
+  float. The `php-semantics` rows are the arbiter.
+- **Codecs.** mbstring substitutes `?`, Python's `errors="replace"` gives
+  U+FFFD, and the two differ in how many characters a bad sequence becomes.
+- **zlib-ng.** CPython on Windows ships zlib-ng, so compressed bytes differ
+  from PHP's; the canon tier is mandatory and CI includes Windows.
+- **Memory and speed.** Memory is accounted, not measured (D7). The renderer
+  is pure Python and measured (D1); its multiple is published, not hidden.

fancy_fine_print-0.1.0/CHANGELOG.md

@@ -0,0 +1,63 @@
+# Changelog
+
+All notable changes to this project are documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+**Pre-1.0, breaking changes land in MINOR releases.** The version number is not
+promising otherwise until 1.0.
+
+## [Unreleased]
+
+## [0.1.0] - 2026-11-07
+
+The first release, and it is **the reader only**: there is no writer and no
+renderer yet. It is a port of PHP fine-print 0.7.0's reader
+(`PHP_REFERENCE = "0.7.0"`), held to PHP by a live oracle rather than by claim.
+Pre-1.0: the API may still change in a minor release.
+
+### Added
+
+- `read(data, *, policy, threshold, excerpts, limits, words)` and
+  `read_unredacted(data, *, threshold, excerpts, limits, words)`: PHP's
+  `Agent::read` / `Agent::readUnredacted`, with the same result shape, the same
+  redaction policies (`redact` by default, `flag`, `discard`), thresholds,
+  findings, notices and refusals (`{"ok": false, "refused": {reason, message}}`).
+  `words=True` gives each page `{text, x0, x1, top, bottom}` boxes, redacted as
+  the page text is (the pdfplumber `extract_words` shape).
+- `page_count(data, limits)`, which raises `RefusedException` as PHP's does.
+- `Document`, the host's raw view: `open()`, `pages()`, `page_text(n)`,
+  `text(n)`, `page_words(n)`, `page_text_with_words(n)`, `metadata()`,
+  `xmp()`, `outline()`, `annotations(n)`, `active_content()`,
+  `encryption()`, `warnings()`, `repaired()`, `version()`.
+- Every PHP guard, with PHP's limits, reasons and messages: file bytes,
+  objects, nesting depth, stream bytes, the decompression ratio and its floor,
+  total decoded bytes, operators, form depth, pages, time and memory. One
+  refusal type, `RefusedException`, and the 12 PHP reasons.
+- Text extraction as PHP's: Flate, LZW, ASCII85, ASCIIHex and RunLength with
+  the PNG and TIFF predictors; simple and Type0 fonts, the four base encodings,
+  `/Differences` and glyph names, `ToUnicode` and encoding CMaps; `TJ`
+  kerning and the layout's word and paragraph gaps; the CTM, `/Rotate` and the
+  crop box; form XObjects; hidden, white, tiny and off-page text.
+- Empty-password decryption (RC4, AES-128, AES-256; R2 to R6) with our own
+  RC4 and AES, the active-content scanner and the agent-read guard.
+- `tests/test_parity_php.py`: PHP fine-print and this port read the same 801
+  files (harvested from PHP's own test suite by
+  `scripts/harvest_php_corpus.php`) through six read variants and must agree,
+  words within 1e-6 pt. A missing PHP fails the suite.
+
+### Changed
+
+- CI checks the PHP reference out at `v0.7.0` (was `v0.5.0`).
+
+### Known differences from PHP
+
+- Memory is ACCOUNTED, not measured (plan decision D7), so a read near
+  `memoryBytes` may refuse at a slightly different point; PHP's second check,
+  the headroom under `memory_limit`, has no Python counterpart.
+- A page-tree warning about a direct (unreferenced) node names it by an object
+  id, which differs between runtimes.
+- Python bounds two loops PHP leaves unbudgeted (reported upstream): the
+  painted-ground lookup behind white-text detection, and a cross-reference
+  stream's rows when `/Index` holds a non-integer count.

fancy_fine_print-0.1.0/CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

fancy_fine_print-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Particle Academy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.