Metadata-Version: 2.4
Name: hakodesh
Version: 0.6.4
Summary: ספר ריק חסר-מארח: טבעו לחשים, קמעות, שומרים ושילובים לפי הצורך. הפרוטוקול כולו בדיאלעקטוס, לטינית בכתב עברי.
Author: Shelleyguitar
License-Expression: LicenseRef-Proprietary
Project-URL: Homepage, https://pypi.org/project/hakodesh/
Keywords: cli,sdk,spells,agents,receipts,akashic,grimoire
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: platformdirs<5,>=4.2
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: hypothesis>=6; extra == "dev"
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Dynamic: license-file

# hakodesh

Host-agnostic Python CLI and SDK. After `pip install hakodesh` the user book is empty. Your LLM or agents **mint** spells, enchantments, wards, and combos as they need them.

PyPI name, import, and command: **hakodesh**.

## Install

```bash
pip install hakodesh
```

Data home: `HAKODESH_HOME` or the platform user-data directory for `hakodesh`. Never `~/spells`.

## Kernel commands

These are the runtime, not starter spells:

| Command | What it does |
|---|---|
| `hakodesh catalog` | User artifacts in the book (empty at install) |
| `hakodesh route "<intent>"` | Rank minted names plus kernel commands |
| `hakodesh invoke <name> [args...]` | Cast a minted spell by name |
| `hakodesh mint <name> --kind spell\|enchantment\|ward\|combo [--like <name> \| --from <path>]` | Scaffold into the book, or mint from a source file (preview; `--confirm` writes) |
| `hakodesh akashic` | Verify HMAC chain; `--tail N` |
| `hakodesh grimoire` | Cast ledger stats |
| `hakodesh grimoire-seal` | RFC 6962 Merkle seal (preview; `--confirm` writes; `--verify`) |
| `hakodesh enchant bind\|lift <name> --settings <path>` | Bind or lift a minted enchantment |
| `hakodesh ward status\|lock\|unlock\|check <name>` | Fail-closed ward kernel |
| `hakodesh combo seal\|cast\|list [name]` | Sealed pipelines of minted spells |
| `hakodesh <minted-name> [args...]` | Cast after mint |

`--like` on an empty book uses the **kind template** in the wheel. After one spell exists, `--like <that>` copies its shape.

Every mint and cast emits `hakodesh.event/v1`. Akashic is SHA-256 linked and HMAC-SHA256 signed. Grimoire is Merkle-sealed with the same chain key. The keystore is `$HAKODESH_HOME/keys` (0700/0600), minted on first seal, never in the wheel.

Notifications default to `none`. The package does not write LaunchAgents or editor hooks until you mint and bind an enchantment.

## עלוקווענטיא: the dialect

The Alter Rebbe's Tanya is known, to those who sit with it closely, for a rigor that does not
stop at the sentence or even the word: every letter is weighed, none placed by habit or
convenience. Read as more than a style, this is *bitul* — a mind that has stopped inserting
its own preference between a letter and what that letter is meant to carry.

hakodesh's protocol is built the same way, for a reason that lives in the code, not the analogy.
`dialectus.generate()` is the *only* source of a token. Not one string in this dialect — no kernel
verb, no spell name, no status, no ward — was chosen by someone looking at it and deciding it
sounded right. Each is the mechanical output of one fixed table of letter mappings, applied
without exception to a Latin root picked for what it means, never for how its transliteration
will look. The test suite enforces this literally: regenerating the whole lexicon from its
lemmas must reproduce a golden snapshot byte for byte, or the build fails. There is no
hand-spelling to protect and no author's ear to please; the namer's will has nowhere left to
intervene between the lemma and the token it becomes.

That is *bitul* applied to language-craft rather than to prayer: not the absence of a self, but
a self that has agreed to stop asserting itself where a rule is meant to govern instead. The
dialect's own name, **עלוקווענטיא** (*eloquentia*, "a speaking-out"), was one candidate among
several built the same mechanical way, screened afterward — along with the rest — for its
gematria, and found alone among them to land, under both standard and expanded counting, on
358: the value of משיח. No one chose its letters to reach that number; the transliteration table
fixed them, the same way it fixes every token here, and 358 is simply what they summed to. The
tradition calls a coincidence like this a *remez*, not a proof, and is right to. It sits well,
though, beside a name for "speaking-out" landing on the value of the sefirah said to hold
nothing of its own — Malchut, the mouth — whose whole work is to take what it is given and speak
it faithfully outward.

The dialect is Hebrew end to end: a **Latin lexicon carried in traditional Hebrew script**, on
the Yiddish and Ladino model. Verbs are the Latin perfect, first person singular (*verificavi*,
*custodivi*, *scripsi* — the same voice as Hebrew's own -תי); objects are Latin nouns; statuses
are perfect passive participles. Prose stays Hebrew; tokens are dialect. The LLM reads the
protocol and converses with the user in the user's own language — that boundary, and only that
boundary, is where English belongs.

Orthography: plene, no nikud; qu→קוו, ph→פ, th→ט, ch→ק, sh→ש, ae/oe→ע, x→קס, f/p→פ, c/k/q→ק,
i/j/y→י, o/u→ו, v/w→וו; doubled letters collapse; word-initial i/o/u take א; an א separates וו
from a vowel ו; final forms on the last letter. Every letter in every token traces back through
this table to the Latin letter that produced it, and every token can be regenerated from nothing
but its lemma and this table — not as a devotional claim, but as the property the test suite
checks on every run.

### Kernel verbs

| עלוקווענטיא | Latin | מה הפועל עושה |
|---|---|---|
| פערקוסי | *percussi* | טבעתי: יצרתי לחש, קמע, שומר או שילוב בספר |
| רעקענסוי | *recensui* | סקרתי: קטלוג הספר |
| דיקסי | *dixi* | דיברתי: הטלתי לחש |
| דירעקסי | *direxi* | ניתבתי: דירוג שמות לכוונה |
| אינקאנטאווי | *incantavi* | קסמתי: קשירה או הסרה של קמע |
| קוסטודיווי | *custodivi* | שמרתי: מצב, נעילה, שחרור ובדיקה של שומר |
| קוניונקסי | *coniunxi* | שילבתי: צינורות חתומים |
| רעפעטיווי | *repetivi* | נזכרתי: אחזור נוהל שמור |
| עקסטולי | *extuli* | העליתי: מעקבים חוזרים לנוהל |
| סקריפסי | *scripsi* | רשמתי: אימות הפנקס |
| סיגנאווי | *signavi* | חתמתי: פנקס ההטלות |
| מעמוראווי | *memoravi* | תיעדתי: רישום מעקב |
| דעקרעווי | *decrevi* | הכרעתי: בחירת נוהל לכוונה |
| קוקורי | *cucurri* | הרצתי: ביצוע נוהל |
| פרוקעסי | *processi* | המשכתי: הצעד הבא |
| ענומעראווי | *enumeravi* | מניתי: רשימת נהלים |
| אפרובאווי | *approbavi* | אישרתי: אישור נוהל |
| סטאטוי | *statui* | קבעתי: מדיניות קידום |
| מענסוראווי | *mensuravi* | מדדתי: מדדי הזיכרון |
| עקסערקוי | *exercui* | תרגלתי: תרחיש סינתטי |
| דעקלאראווי | *declaravi* | הצהרתי: חוזה האירועים |

`devra --help` lists exactly these under `lexicon`. The traditional-Hebrew twins of 0.3/0.4
(טבעתי, שמרתי, ...) and the English names still dispatch as **silent legacy aliases through
0.5.x** and are removed in 0.6.0. All spellings are reserved: `mint` refuses them as a whole
artifact name.

### Status vocabulary

Closed and declared by `protocol`: פערמיסום (*permissum*), קומפלעטום (*completum*), נעגאטום (*negatum*), דעפעקטום (*defectum*), קלאוסום (*clausum*), פרעוויסום (*praevisum*), אינקעפטום (*inceptum*), סינקרונאטום (*synchronatum*), אפערטום (*apertum*), וועריפיקאטום (*verificatum*), and the rest in `dialectus.STATUS`. Event kinds,
notification policies, severities, actor roles, trace sources, outcomes, correctness, procedure
statuses and decisions are written in the dialect and **read in either spelling** within
`hakodesh.event/v1`; the published descriptor lists both. JSON keys stay English until the
`v2` schema bump (0.6.0).

### Errors

Every kernel error carries a stable `error_code` (`ward.unknown`, `mint.reserved`, ...) and
Hebrew prose. Tests assert on codes, never on prose. Artifact names may be lowercase Latin or
Hebrew, digits and dashes; every lookup normalizes to NFC.

```bash
דיקסי רעקענסוי                          # == devra spellbook
devra פערקוסי פרובאווי-קאנון --confirm   # mint a dialect-named spell
devra פרובאווי-קאנון                     # cast it; receipts land in receipts/פרובאווי-קאנון/
```

## Development

```bash
python -m pip install -e ".[dev]"
python -m pytest                 # unit, property and tripwire tests
python -m build                  # wheel + sdist into dist/
```

The package depends on nothing but `platformdirs`. It has no opinion about where your source
of truth lives or how you publish; nothing in the wheel or the sdist names a host, a storage
account or a vault, and `tests/test_agnostic.py` keeps it that way.

## SDK

```python
from hakodesh.catalog import catalog
from hakodesh.mint import mint
from hakodesh import events, akashic, grimoire
from hakodesh.enchant import bind, lift
from hakodesh.ward import unlock
from hakodesh.combo import seal, cast
```

## Book law

The book is per user, under `HAKODESH_HOME`. A fresh install has zero spells, enchantments,
wards or combos, and nothing is intrinsic: discovery picks up a file the moment it lands under
`HAKODESH_HOME/book/`. The repository's `workshop/` is a book as *source*: mint from it with
`--from`; it is not in the wheel and never lands in a book by itself (`docs/PROTOCOL.md`, §Book law).
