baghban 0.1.0__tar.gz

baghban-0.1.0/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+## 0.1.0 (unreleased)
+
+First version.
+
+- Reader for `.bonsai` files: types resolved through xmlns, `Combinator`,
+  `Source` and `Disable` unwrapped, nested workflows, Bonsai's scoping rules
+  (groups and includes transparent, other nested workflows real scopes),
+  includes resolved from the top-level folder or, with `--resource-root`,
+  from embedded resources; include property overrides applied, through
+  nested includes too.
+- Findings: `SILENT_OVERWRITE`, `FAILS_ON_REPEAT`, `DUPLICATE_OUTPUT`,
+  `DANGLING_SUBJECT`, `DUPLICATE_SUBJECT`, `MISSING_INCLUDE`,
+  `RECURSIVE_INCLUDE`, `INVALID_INCLUDE`, `DISABLED_WRITER`,
+  `APPENDS_ACROSS_RUNS`, `UNUSED_SUBJECT`; what could not be checked is
+  reported, not guessed.
+- Commands: `check`, `show`, `render` (HTML, Mermaid, DOT), `diff`, `deps`,
+  `params`, `fingerprint` (with `--fields` for daftar).
+- Tests: 113, including agreement with Bonsai's own test workflows.

baghban-0.1.0/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

baghban-0.1.0/MANIFEST.in

@@ -0,0 +1,4 @@
+include README.md TESTING.md ROADMAP.md CHANGELOG.md LICENSE NOTICE
+recursive-include tests *.py *.bonsai *.md LICENSE
+recursive-include examples *.py *.bonsai
+global-exclude __pycache__ *.pyc *.html

baghban-0.1.0/NOTICE

@@ -0,0 +1,11 @@
+baghban
+Copyright 2026 Aslan Satary Dizaji
+
+Licensed under the Apache License, Version 2.0 (see LICENSE).
+
+tests/data/bonsai_upstream/ contains test workflows copied unchanged from
+Bonsai (https://github.com/bonsai-rx/bonsai), Copyright (c) 2011-2025 Bonsai
+Foundation CIC and Contributors, under the MIT licence
+(tests/data/bonsai_upstream/LICENSE). They are used only as test data.
+
+baghban reads the .bonsai file format; it contains no Bonsai code.

baghban-0.1.0/PKG-INFO

@@ -0,0 +1,342 @@
+Metadata-Version: 2.4
+Name: baghban
+Version: 0.1.0
+Summary: Check, draw and compare Bonsai workflows on any machine, before the rig runs.
+Author: Aslan Satary Dizaji
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/aslansd/baghban
+Project-URL: Issues, https://github.com/aslansd/baghban/issues
+Keywords: bonsai,bonsai-rx,neuroscience,experiments,lint,reproducibility
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Provides-Extra: provenance
+Requires-Dist: daftar; extra == "provenance"
+Dynamic: license-file
+
+# baghban
+
+**باغبان** — *bağban, gardener.* The same word in Persian and Azerbaijani.
+Someone has to tend the bonsai.
+
+**Know what will go wrong with a Bonsai rig before the session runs.**
+baghban reads [Bonsai](https://bonsai-rx.org) workflow files and reports the
+faults that lose data without an error: a writer that overwrites every trial,
+two cameras recording into one file, a logger left disabled after debugging,
+a subject name with a typo. It also draws, compares and fingerprints
+workflows, so you can review a rig from a Mac or Linux laptop.
+
+```
+pip install baghban
+```
+
+Python 3.10+. Apache 2.0. **No dependencies. No Windows, no .NET, no Bonsai
+installation.** baghban reads the `.bonsai` XML; it never runs a workflow.
+
+---
+
+## The failure that matters
+
+Bonsai's costliest bugs do not crash anything. The workflow builds, the
+cameras light up, the session runs for an hour, and the problem surfaces weeks
+later in analysis:
+
+- A `CsvWriter` inside a per-trial `SelectMany` with `Overwrite=True` and
+  `Suffix=None` is opened again for every trial and replaces the file each
+  time. After 200 trials, the file holds trial 200.
+- A camera-recording module included twice, without giving each copy its own
+  file name, sends both cameras to `camera.avi`.
+- A writer disabled while debugging a sensor stays disabled. Nothing is
+  recorded, and nothing says so.
+
+Each of these is fully determined by the workflow file. None of them is
+reported by Bonsai before the data is gone.
+
+---
+
+## The thirty-second version
+
+```
+$ baghban check rig/foraging.bonsai
+
+[error] DUPLICATE_OUTPUT  Include 'modules/CameraRecorder.bonsai' #3 > VideoWriter 'camera.avi' #1
+    Another writer also writes 'camera.avi' (Include 'modules/CameraRecorder.bonsai' #1 >
+    VideoWriter 'camera.avi' #1). Two writers cannot hold the same file: one of them fails,
+    or they overwrite each other. This is common when a module containing a writer is
+    included twice without giving each copy its own file name.
+    fix: Give each writer its own file name; for included modules, externalize FileName and
+    set it on each IncludeWorkflow.
+
+[error] SILENT_OVERWRITE  SelectMany 'Trial' #6 > CsvWriter 'trial.csv' #2
+    Overwrite=True with Suffix=None inside SelectMany 'Trial': the writer is opened again
+    for every element (e.g. every trial), and each time it replaces 'trial.csv'. Only the
+    last element's data survives the session.
+    fix: Use Suffix=Timestamp or FileCount to keep one file per element, or move the writer
+    after the SelectMany to collect all elements in one file.
+
+[error] DANGLING_SUBJECT  SubscribeSubject 'TrialEnds' #8
+    No subject named 'TrialEnds' is declared in this scope or any enclosing one, so Bonsai
+    will fail to build the workflow.
+    fix: Did you mean 'TrialEnd'?
+
+[warning] DISABLED_WRITER  CsvWriter 'licks.csv' #11
+    This CsvWriter is disabled, so nothing will be written to 'licks.csv'. Disabling a
+    writer while debugging and forgetting to re-enable it loses whole sessions without an
+    error.
+    fix: Re-enable it, or delete it if the data is not needed.
+
+3 errors, 1 warning, 1 info in 22 nodes.
+```
+
+That is `examples/rig_v1`, a foraging rig with two cameras, a lick sensor
+and 10 s trials. `examples/rig_v2` is the same rig fixed, and checks clean.
+`check` exits 1 when there are errors, so it can gate a commit or a CI run.
+
+`#n` is a node's position in its own workflow, as in the XML, which is how
+the two copies of the included module are told apart.
+
+---
+
+## Findings
+
+| Finding | Severity | Question it answers |
+| --- | --- | --- |
+| `SILENT_OVERWRITE` | error | Will a writer replace data from an earlier run, or from an earlier trial in the same run, without an error? |
+| `FAILS_ON_REPEAT` | error | Will a writer inside a per-trial loop raise "file already exists" on trial 2 and end the session? |
+| `DUPLICATE_OUTPUT` | error | Do two writers write to the same file? |
+| `DANGLING_SUBJECT` | error | Does a `SubscribeSubject` or `MulticastSubject` name a subject that is not declared where it can see it? |
+| `DUPLICATE_SUBJECT` | error | Are two subjects with one name declared in the same scope? |
+| `MISSING_INCLUDE` | error | Does an `IncludeWorkflow` point at a file that does not exist? |
+| `RECURSIVE_INCLUDE` | error | Do workflows include each other in a cycle? |
+| `INVALID_INCLUDE` | error | Is an included file not a readable workflow? |
+| `DISABLED_WRITER` | warning | Is a writer (or a group holding one) disabled, so nothing is recorded? |
+| `APPENDS_ACROSS_RUNS` | info | Does every run append to the same file, and repeat the CSV header mid-file? |
+| `UNUSED_SUBJECT` | info | Is a subject declared but never subscribed to? |
+
+`SILENT_OVERWRITE` drops to a warning when the file name is externalized:
+then it is only safe if the launcher sets a new name each run, which baghban
+cannot see.
+
+### How it decides
+
+baghban models the parts of Bonsai's build process the checks depend on, as
+the Bonsai source implements them (Bonsai.Core, Bonsai.System):
+
+- **Scopes.** `GroupWorkflow` and `IncludeWorkflow` build in a `GroupContext`
+  that forwards every declaration to its parent, so a subject declared inside
+  a group is visible beside it. Every other nested workflow (`SelectMany`,
+  `Defer`, `CreateObservable`, ...) builds in a new `BuildContext`: lookups
+  fall back outwards, declarations stay inside. Declaring a name twice in one
+  build context is a build error.
+- **Loops.** `SelectMany`, `CreateObservable` and `WindowWorkflow` subscribe
+  their nested workflow once per input element, so a writer inside one is
+  opened once per element, typically once per trial.
+- **Writers.** `CsvWriter` and the `FileSink`/`StreamSink` families
+  (`VideoWriter`, `TextWriter`, `AudioWriter`, `MatrixWriter`, `ImageWriter`)
+  open their file on subscription, check `File.Exists(path) && !Overwrite`,
+  then create it. Any operator with `Suffix` plus `FileName` or `Path` is
+  treated as a writer, which also covers third-party writers that follow the
+  convention.
+- **Includes.** Paths are opened relative to the working directory, which
+  the editor sets to the top-level workflow's folder. baghban resolves nested
+  includes the same way: relative to the top-level file, not to the file
+  containing the include. Values written on an `IncludeWorkflow` set the
+  included file's externalized properties, and baghban applies them, through
+  nested includes too, so checks see the effective file names.
+- **Disabled nodes** are not built: a disabled subject declares nothing, and
+  a disabled include is not opened.
+
+### Staying quiet when it cannot know
+
+A checker that cries wolf on good rigs gets switched off. When the XML is not
+enough to be sure, baghban says what it did not check instead of guessing:
+
+- an include it cannot open (an embedded resource of a NuGet package, or an
+  absolute Windows path on a Mac) suspends subject checks in that scope,
+  because the include may declare the subject;
+- a file name assigned from data at run time (`PropertyMapping`,
+  `InputMapping`) is not judged;
+- types are not checked, because baghban has no catalogue of what each
+  package contains.
+
+These appear as `not checked:` lines under the report.
+
+---
+
+## Checked against something that does not depend on it
+
+Bonsai's own test suite ships 30 small workflows and asserts which of them
+fail to build (`WorkflowRunnerTests`, `IncludeWorkflowTests`). They are
+included unchanged in `tests/data/bonsai_upstream` (MIT licence), and baghban
+must agree with Bonsai on every one:
+
+| Bonsai's expectation | baghban |
+| --- | --- |
+| `*BuildException` workflows fail to build (undeclared `MulticastSubject`, directly and through file and embedded includes) | `DANGLING_SUBJECT` |
+| `IncludeWorkflowSelfOuter` fails to build (self-inclusion) | `RECURSIVE_INCLUDE` |
+| `IncludeWorkflowMissing` fails to build (missing nested include) | `MISSING_INCLUDE` |
+| `*RuntimeException` workflows build, then fail while running (division by zero) | no findings: not a static problem |
+| `NestedSubscribeSubjectWithClosestRedefinition` builds | no findings |
+| `MissingTypes` names a type that does not exist | no findings: baghban does not guess about types |
+| Nested include property: the outer include's `OuterCount = 2` reaches the inner `Take.Count` | `Take.Count == "2"` |
+
+On the file-writer findings, where Bonsai has no test fixtures, each finding
+is tested in both directions on paired workflows: it must fire where the fault
+exists and stay quiet on the nearest workflow without it (see `TESTING.md`).
+
+---
+
+## Commands
+
+```
+baghban check  WORKFLOW|DIR ...      findings; exit 1 on errors (--strict: on warnings too)
+baghban show   WORKFLOW              the workflow as a tree
+baghban render WORKFLOW [-f html]    draw it: html (default), mermaid, dot
+baghban diff   A B                   what changed, by meaning; exit 0 if equivalent
+baghban deps   WORKFLOW              assemblies (= packages) and includes it needs
+baghban params WORKFLOW              externalized properties and their values
+baghban fingerprint WORKFLOW         content hash, stable across re-saves (--fields for daftar)
+```
+
+`check` accepts folders. A file that another checked file includes is checked
+through its includer, where the subjects and file names it relies on are
+defined, rather than on its own. Every command takes `--resource-root
+ASSEMBLY=DIR` to follow embedded-resource includes (`Path="MyPackage:Module.bonsai"`)
+into a package's source folder.
+
+### See a workflow without the editor
+
+```
+baghban render rig/foraging.bonsai && open foraging.html
+```
+
+writes one HTML page with the graph (nested workflows as boxes, disabled nodes
+dashed, nodes with findings outlined in red or orange), the findings table and
+a text outline. It loads the Mermaid script from a CDN, so it needs a network
+connection to draw. `-f mermaid` output also renders directly in GitHub
+markdown and pull requests.
+
+### Diff by meaning
+
+Nodes are addressed by position in the XML, so inserting one node renumbers
+every edge after it, and `git diff` becomes noise. `baghban diff` matches
+nodes by what they are: named nodes by type and name, others by type and
+occurrence ("the second CsvWriter in the Trial SelectMany"):
+
+```
+$ baghban diff rig_v1/foraging.bonsai rig_v2/foraging.bonsai
+
+~ CsvWriter#1 ('licks.csv')  enabled
++ CsvWriter#2 ('trials.csv')
+~ Include(modules/CameraRecorder.bonsai)  FileName: (unset) -> left.avi
+~ Include(modules/CameraRecorder.bonsai)/VideoWriter ('left.avi')  Suffix: None -> Timestamp
+- SelectMany:Trial/CsvWriter ('trial.csv')
++ SubscribeSubject:TrialEnd
+- SubscribeSubject:TrialEnds
+~ Timer  Period: PT10S -> PT12S
+...
+```
+
+Included files are expanded, so a change inside a module shows up under each
+include that uses it. Inserting an unrelated node does not disturb other keys;
+it does shift the keys of later unnamed nodes of the same type in the same
+workflow, which naming them avoids.
+
+---
+
+## Python
+
+```
+import baghban
+
+doc = baghban.load("rig/foraging.bonsai")
+report = baghban.check(doc)
+print(report.summary())
+report.errors               # [Finding(code, severity, message, location, file, node, hint)]
+
+for node in doc.walk():     # every node, includes expanded
+    if node.is_writer:
+        print(node.location(), node.properties)
+
+baghban.diff(baghban.load("v1.bonsai"), baghban.load("v2.bonsai")).summary()
+baghban.fingerprint(doc)
+baghban.mermaid(doc)
+```
+
+---
+
+## Provenance, with daftar
+
+A session's data is only as interpretable as the record of the protocol that
+produced it, and that protocol is a `.bonsai` file plus its includes plus the
+parameter values it ran with. `baghban.manifest_fields` turns that into flat
+fields for [daftar](https://pypi.org/project/daftar/):
+
+```
+with daftar.track("session-0412", params=baghban.manifest_fields(doc)) as run:
+    ...
+```
+
+```
+$ baghban fingerprint rig_v2/foraging.bonsai --fields
+{
+  "bonsai.workflow": "examples/rig_v2/foraging.bonsai",
+  "bonsai.version": "2.9.0",
+  "bonsai.fingerprint": "fc07dd88c5331b2dfeb53671f5e05cd80b03f49e96060cb58a745b1682b600fd",
+  "bonsai.param.TrialInterval": "PT12S",
+  "bonsai.include.modules/CameraRecorder.bonsai": "ok"
+}
+```
+
+The fingerprint ignores whitespace, attribute order, namespace prefixes and
+the `Version` stamp the editor writes on every save, and changes with every
+operator, property value, edge, disabled flag and included file's content.
+Two sessions that ran the same protocol then diff as identical in daftar,
+even when someone re-saved the file in between.
+
+---
+
+## Try it
+
+```
+python examples/demo.py
+```
+
+Shows, checks, fixes, diffs and fingerprints the example rig, and writes
+`examples/rig_v1.html`.
+
+## Status
+
+Research prototype, honestly labelled.
+
+- The findings are grounded in the Bonsai source and agree with Bonsai's own
+  test suite, but have not yet been run across a broad set of real rigs. How
+  often they fire on published workflows, and how often wrongly, is the next
+  thing to measure (see `ROADMAP.md`).
+- No finding has yet been confirmed by running a workflow. `Bonsai.Player`
+  runs on macOS under .NET 8, so the writer findings can be confirmed on a Mac
+  by running the fixtures and watching the files; that is on the roadmap.
+- Embedded-resource includes from installed NuGet packages are not followed
+  yet unless you point `--resource-root` at the package source.
+- Timing problems (unbounded `Zip` queues, timestamps taken after heavy
+  processing) need stream rates the XML rarely states, and are not checked.
+
+## Development
+
+```
+pip install -e ".[dev]"
+pytest -q
+```
+
+## Licence
+
+Apache 2.0. `tests/data/bonsai_upstream` contains test workflows from Bonsai
+(MIT); see `NOTICE`. baghban contains no Bonsai code.