Metadata-Version: 2.5
Name: yidl-undoable
Version: 0.1.1
Summary: YIDL generated transactional data classes with sparse undo history
Project-URL: Repository, https://github.com/owebeeone/yidl-undoable
Project-URL: Documentation, https://github.com/owebeeone/yidl-undoable/blob/main/docs/API.md
Project-URL: Issues, https://github.com/owebeeone/yidl-undoable/issues
Requires-Python: <3.16,>=3.12
Requires-Dist: astichi>=1.1.3
Requires-Dist: yidl-lifecycle>=0.1.0
Requires-Dist: yidl>=0.1.0
Provides-Extra: dev
Requires-Dist: hatchling>=1.24; extra == 'dev'
Requires-Dist: pytest>=7; extra == 'dev'
Provides-Extra: regenerate
Requires-Dist: yidl-dataclass==0.1.1; extra == 'regenerate'
Description-Content-Type: text/markdown

# YIDL Undoable

Generate application data classes with transactions and frame-based undo/redo.
Managed data has immutable sparse histories; caches, constants and resources have
shared nonversioned storage. CPython 3.12–3.15 is supported.

The original transaction implementation is accepted after independent Code/Surface
and State review. The optional comparison extension is also accepted as a
functional/package candidate after both independent Dataclass final
reviews reported GO. See the [Dataclass final result](https://github.com/owebeeone/yidl-dataclass/blob/main/dev-docs/Dataclass-FinalReviewResult.md)
for that acceptance boundary, and the [experiment results](https://github.com/owebeeone/yidl-undoable/blob/main/dev-docs/ExperimentResults.md) for the
TDD evidence, Python-version checks, elapsed time, observed cost and scope.

```python
from yidl_undoable import UndoRedoManager, const, local_store, managed, undoable

@undoable
class Document:
    name: str = const(default="document")
    items: tuple[str, ...] = managed(default=(), thaw=list, freeze=tuple)
    cache: dict[str, object] = local_store(default_factory=dict)

history = UndoRedoManager()
document = Document(transaction_manager=history)
history.initialize(document)
with history.begin():
    document.working.items.append("first")
assert history.undo() and document.items == ()
assert history.redo() and document.items == ("first",)
```

The manager owns begin, commit, rollback and validation. A successful outer scope
exit publishes one frame; an exceptional exit rolls back the entire joined edit.
Unmarked annotations are ordinary `field` values. Use `managed` for data that
rollback and navigation must restore.

`node.default` is the ordinary live handle. It reads pending values while editing.
`node.current` reads the selected committed frame; `node.working` may thaw a field
once in the active transaction. Child views propagate through managed relationships.
Holding these handles follows the cursor. `history.snapshot()` instead pins committed
managed data, including nested aliases, across later edits and branches.

Initialize one or more same-manager roots after setup construction. New objects
require an edit after initialization; provisional objects can be edited before
attachment. Managed relationships must be acyclic; aliases and empty final root
sets are supported. Strict absent reads raise by default. `ReadLastVisible()`
resolves prior visible data and pins descendants to that fallback frame.

Supported declarations wrap unchanged Lifecycle markers: `managed`, `const`, `field`, `binding`,
`local_store`, `lazy`/`static`, `transient`, `initvar`, and `classvar`.
`validate_commit(DEFAULT_TRANSACTION)` marks a pure candidate validator.
Constants keep one reference; their contents can still change. Bindings require
Lifecycle `BindingBase` values (or mappings of them). Resources remain application-owned;
undo never closes, accepts, reopens or rewinds them.

`@undoable` defaults to `eq=False, order=False`, preserving node-state identity
and hashing. `@undoable(eq=True)` generates exact-facade-class logical equality;
`order=True` requires `eq=True`. Default/current/working classes compare their
own exposed values and return NotImplemented across view/model classes. Enabled
facades are unhashable, including pinned handles. SnapshotNode identity stays
unchanged. Eligible fields accept boolean `compare=True`; managed fields separately
accept `write_compare="value"` or `"identity"`. InitVar/ClassVar/transient/local
fields are excluded. Legacy managed `compare="value"|"identity"` remains supported,
with logical inclusion=True; combining it with explicit write_compare fails.

During synchronous value-write comparison, enabled facade equality uses historical
node-state identity. This includes equality called by opaque user callbacks. Native
`bool(old == value)` still receives the original operands inside the manager fence;
identity writes remain `old is value`. A private expiring ContextVar marker limits
this rule to the active comparison. Escaped copied contexts revert to structural
equality after it closes. Hashing and ordering never switch. The scope does not
authorize manager mutation or concurrent manager operations.

History is in-memory and linear. Committing after undo discards redo; prior snapshots
retain their original epoch. One manager has one key and cursor. Disk persistence,
resource ownership/hooks, multiple generated bases, custom stored stable-value
adapters, thread/task isolation and multi-key atomic edits are outside this version.
Callbacks must be pure; same-manager transactional reentry is rejected. Escaped
working containers remain ordinary Python objects but are detached on completion.

See the [API and field guide](https://github.com/owebeeone/yidl-undoable/blob/main/docs/API.md), [generation architecture](https://github.com/owebeeone/yidl-undoable/blob/main/docs/Architecture.md),
[executable examples](https://github.com/owebeeone/yidl-undoable/blob/main/examples/first_use.py), and [TDD evidence](https://github.com/owebeeone/yidl-undoable/blob/main/dev-docs/TddEvidence.md).

The comparison candidate is verified with original Astichi 1.1.3, YIDL 0.1.0 and
Lifecycle 0.1.0 wheels in isolated environments. SDKs/Lifecycle are reference-only
for this experiment. Regeneration additionally requires the pinned
`yidl-dataclass==0.1.1` build extra: it loads the authoritative shared
comparison resource, verifies its SHA256 and embeds it into this package's base.
Normal model generation has no Dataclass runtime dependency or sibling-resource
lookup. Existing development `tool.uv.sources` is not the experiment install route;
use explicit locked wheels rather than resolving those sibling checkouts.

Run `python -m pytest -q`, `python -m yidl_undoable.regenerate_undoable_base`, and
`python tests/regenerate_golden.py` in that environment. Regeneration checks by
default; `--write` updates authored-source artifacts. Consumer packaging uses
`python -m hatchling build`. [E/F evidence](https://github.com/owebeeone/yidl-undoable/blob/main/docs/validation/stage-ef/README.md)
records actual commands, failures, original wheel/resource provenance and limits.
No release or new performance result is claimed.

## Autonomous implementation experiment

The [experiment results](https://github.com/owebeeone/yidl-undoable/blob/main/dev-docs/ExperimentResults.md) record **2h 25m 50s**
from autonomous go-ahead (**2h 37m** including earlier design preparation),
**$20.87 Standard API-equivalent estimated cost**, and **215 tests passing**
on Python 3.12–3.14. Actual Codex billing is unavailable. Final Code/Surface and
State reviews both reported GO after five bounded runtime correction cycles.

The [complete experiment record](https://github.com/owebeeone/yidl-undoable/blob/main/dev-docs/README.md) includes the archived
original concept, design, TDD plan and observed red/green evidence, every
review/report/prompt/remediation plan, supported-version and isolated-wheel
verification, timestamps, raw sanitized token counters and cost calculations.
The [publication record](https://github.com/owebeeone/yidl-undoable/blob/main/dev-docs/Publication.md) distinguishes this later
GitHub upload from the completed experiment's measurements.

Install with `python -m pip install yidl-undoable`. Releases use Gearu and
`.github/workflows/publish.yml`; see [RELEASE.md](https://github.com/owebeeone/yidl-undoable/blob/main/RELEASE.md).
For base regeneration, install the `regenerate` extra, which pins its shared
Dataclass comparison authority. It is not a runtime dependency.

Known limitation: a field named `schema` currently fails during decoration. Use
another name; this existing capture collision is recorded in the release audit.
The proposed `undoable_leaf` helper remains unimplemented; initialize roots with
`history.initialize(*roots)`.
