Metadata-Version: 2.4
Name: hakodesh
Version: 0.5.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 protocol is Hebrew end to end, in a constructed dialect: a **Latin lexicon carried in
traditional Hebrew script**, on the Yiddish and Ladino model. Every protocol token is derived
from a Latin lemma by one total transliteration (`hakodesh.dialectus`), so it is a novel string
with no prior corpus meaning, yet an English reader can decode it through its Latin root.
Verbs are the Latin perfect, first person singular (*verificavi*, *custodivi*, *scripsi*); 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.

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.

### 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).
