Settle and document the public Python API before 1.0 #3577

Summary

polyfile/__init__.py exports a public Python API — Matcher, Parser, PARSERS,
register_parser, Submatch, Match, InvalidMatch — but nothing states what a caller may rely
on. There is no py.typed marker, no documented contract, and no deprecation policy. Before
declaring 1.0, decide what that surface is and write it down.

This is an entry criterion for the v1.0.0 milestone, not a defect.

Why now

The v0.6.0 cycle changed that surface repeatedly, which is the evidence that it is not yet settled:

• try_all_offsets was removed from Matcher.__init__ and Analyzer.__init__ (try_all_offsets is accepted and ignored, and the CLI flag for it is commented out #3465). It had been
  accepted and ignored since it was introduced.
• Matcher.match changed behavior substantially for an already-open stream (Matcher.match() returns almost no structure when given an open stream instead of a path #3463): it previously
  returned 1 match where a path returned 51.
• FileStream.__init__'s length parameter had two contradictory meanings depending on which
  branch ran (Count a FileStream's length from its start in both branches #3561). One was chosen and documented; nothing had recorded which was intended.
• Both "Extending PolyFile" examples in CLAUDE.md were non-functional, and the register_parser
  example documented the wrong shape entirely — it decorated a class, where register_parser wraps
  its argument in a function wrapper (Documentation describes a PDF parser and a registration API that were both replaced #3467). Anyone following the guide got
  TypeError: MyParser() takes no arguments.

A 1.0 version number promises that breaking changes wait for 2.0. That promise is only meaningful if
the surface it covers is defined.

What this needs

1. Decide what is public. polyfile/__init__.py's exports are the current de facto answer, but
   Analyzer, MagicMatcher, MagicTest, FileStream and MatchContext are all reachable and
   used by the documented extension points. Either bring them in deliberately or state that they are
   internal.
2. Write the contract. docs/extending_polyfile.md exists and should carry it: what a custom
   matcher and a custom parser must implement, what they may rely on, and what the library
   guarantees across minor versions. The corrected examples from Documentation describes a PDF parser and a registration API that were both replaced #3467 are the starting point.
3. Add a py.typed marker so type checkers see the annotations the package already carries, and
   decide whether the annotated signatures are part of the contract.
4. Settle Implement all-offsets scanning for embedded file detection #3532 first, or state that it is out. Implementing all-offsets scanning would change
   Matcher's behavior and possibly its constructor. Deciding that after 1.0 means either breaking
   the promise or shipping it awkwardly.
5. State a deprecation policy. One minor release with a warning is the usual shape; any policy
   is better than none.

Related

• Implement all-offsets scanning for embedded file detection #3532 — all-offsets scanning, which would change Matcher
• Documentation describes a PDF parser and a registration API that were both replaced #3467 — the documentation defects that revealed the extension API was undocumented in practice
• Matcher.match() returns almost no structure when given an open stream instead of a path #3463, try_all_offsets is accepted and ignored, and the CLI flag for it is commented out #3465, Count a FileStream's length from its start in both branches #3561 — the v0.6.0 changes to this surface