Beyond Babel v0.3.0

First release since v0.1.0. It includes the changes tagged as v0.2.0, which was never released on GitHub. This release covers 109 commits. It includes two breaking changes, a storage layout change and a new import syntax.

Worked examples live in the transcripts/ folder. Each one is a runnable session that the test suite replays.

bb.py was also used in the experiment described in AI without IA ("The program is not its text"). That article compares agents writing plain files with agents writing bb.py functions. Its 20-task pilot found one agent writing through bb.py about as good as one writing files (75.9% against 78.2%). It does not show that bb.py is better, and the article says so.

Highlights

Edit and save workflow

• bb edit NAME@lang FILE writes a markdown edit file. It contains the code, the documentation and the checks. When you run it again, it saves from that file. See transcript 08.
• bb edit can start a new function. It refuses a new name for code already in the pool.
• bb scratchpad saves several functions from one markdown file. --refactor ROOT then brings ROOT up to date. See transcript 03 for bb refactor.
• bb translate NAME@lang TARGET FILE translates through a file. --tree ROOT@lang translates a whole tree in one file. See transcript 00 and transcript 05 for multilingual functions.
• Long statements are pretty-printed to 100 columns, and multi-line strings show as triple-quoted literals.

Checks are part of a function's identity

• Checks are attached to the function and included in its hash. Changing checks forks the function. Changing documentation does not.

• The @check decorator and the bb check command are gone. Checks now run as part of review and validation.

• A failing check reports what it returned, which part was false and what it compared.

• Checks may call pool functions you saved yourself.

• A check is a function whose single parameter is named after the function under test. bb passes it the implementation, so a check never imports a hash. It passes when it returns a truthy value. For example, in an edit file for fibonacci:

  def check_fibonacci_recurrence(fibonacci):
      """Check f(n) == f(n-1) + f(n-2) for n up to 20."""
      return all(fibonacci(n) == fibonacci(n - 1) + fibonacci(n - 2) for n in range(2, 21))

  A full edit file with checks is in transcript 08.

Pool references: bb.ref and bb.resolve

• Normalization 4: stored code refers to pool functions as bb.ref("<hash>"), so the hash is the same in every language.
• Authoring: write import bb, then f = bb.resolve("f") for a name resolved when saving. Use bb.ref("<hash>") to pin a version. bb.latest does the same as bb.resolve.
• Removed: from bb.pool import ... is refused. Objects stored with object_<hash> imports still load.
• Drafts: they name every reference, record pins and list debt.

Lineage, versions and gradual updates

• Lineage v2: pool/ now holds functions/, mappings/ and lineage/. Current versions follow append-only lineage steps per language and name, never time. Relations are add, edit, document, rename, refactor, restore and translate.
• Translations: an edit in one language leaves the others on their version, waiting for a translation ("not yet translated").
• Shared code: two names can share one code. One caller using two names of the same code is refused.
• Migration: run bb migrate to convert old pools. Other commands refuse the old layout.
• New commands: bb update NAME@lang updates a function at once, bb rm NAME@lang removes a function that is no longer in use, and bb log NAME@lang shows one name's history.
• Version handling: going back to an older version makes it current again. bb rm says when the previous version is current again.

Finding and understanding code

• bb search with no query lists the pool. It has --json, --outdated, --diverged and --uses options.
• Similarity: bb search --similar finds functions whose code looks like another's. Saving warns about near-copies.
• Callers and trees: bb caller NAME@lang lists current callers and bb tree shows the call tree. bb latest --hash prints the hash. See transcript 06 and transcript 07.

Review, trust and sharing

• Reviews are signed records shared through git, and trusted peers are listed explicitly. See transcript 10.
• Private state (config, approvals, trusted peers) lives in $BB_STATE_DIRECTORY, so nobody can approve code for you through git.
• bb run is gated by review (see transcript 04), and bb compile needs no review. --dangerously-unreviewed is available for disposable machines.
• Removed: bb commit and bb remote. Sharing the pool is git's job, and bb never runs git.
• Worklogs: translatable notes attached to function translations, shown in bb log. See transcript 09.

Normalization and robustness

• Exception handler variables and classes defined inside functions are renamed with their uses.
• import a.b keeps its top-level name.
• Names bound by imports inside a function body are never renamed.
• The normalization version is recorded for each function.
• Saving refuses functions that read a name defined nowhere, keyword arguments that bb's placeholders cannot receive, and files whose module-level code bb would silently drop.
• Python 3.14 is supported.

Packaging and docs

• The PyPI project is now beyondbabel, published by a GitHub Action on version tags.
• Local development is pinned to Python 3.11, the oldest supported version.
• New and updated docs: BB.md, CONTRIBUTING.md (which replaces SKILLS.md) and the module docstring on writing pool functions. Transcripts 06–10 cover near-copies, edit and check, worklogs and shared reviews.

Upgrading from v0.1.0

1. Run bb migrate on existing pools.
2. Replace from bb.pool import x with import bb and x = bb.resolve("x").
3. Replace @check decorators with checks in the edit file.
4. Replace bb commit and bb remote with plain git on $BB_DIRECTORY.

Full changelog: v0.1.0...v0.3.0