Metadata-Version: 2.4
Name: hakodesh
Version: 0.8.1
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. Version 0.8 adds package-owned, explicit Claude Code setup; 0.8.1 adds an opt-in persistent reader. Installation never edits host settings or installs hooks.

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

## Install

```bash
pip install hakodesh
hakodesh --help
hakodesh אינסטיטוי --help
```

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 רעקענסוי` | User artifacts in the book (empty at install) |
| `hakodesh דירעקסי "<intent>"` | Rank minted names plus kernel commands |
| `hakodesh דיקסי <name> [args...]` | Cast a minted spell by name |
| `hakodesh פערקוסי <name> --kind spell\|enchantment\|ward\|combo [--like <name> \| --from <path>]` | Scaffold into the book, or mint from a source file (preview; `--confirm` writes) |
| `hakodesh סקריפסי` | Verify HMAC chain; `--tail N` |
| `hakodesh סיגנאווי` | Cast ledger stats |
| `hakodesh סיגנאווי seal` | RFC 6962 Merkle seal (preview; `--confirm` writes; `verify`) |
| `hakodesh אינקאנטאווי bind\|lift <name> --settings <path>` | Bind or lift a minted enchantment |
| `hakodesh קוסטודיווי status\|lock\|unlock\|check <name>` | Fail-closed ward kernel |
| `hakodesh קוניונקסי seal\|cast\|list [name]` | Sealed pipelines of minted spells |
| `hakodesh אינסטיטוי ...` | Preview and explicitly manage supported host setup; see [Onboarding](docs/ONBOARDING.md) |
| `hakodesh reader persistent ...` | Import and query reader state only with caller-supplied paths and scope |
| `hakodesh קונסולטאווי ...` | Run the local reader functional pilot; it is not a production remote reader |

`--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 during installation. Claude Code hooks are written only by `hakodesh אינסטיטוי claude apply --confirm`.

## Persistent reader (opt-in)

Start with `hakodesh reader persistent --help`. Persistent commands require an explicit
`--state` path and, for source operations, the source file, its inventory, and caller-supplied
source, provider, and scope identifiers and revisions. The package does not choose a state
location or migrate a reader state because the package version changed.

`ingest` consumes a saved `raw-worker/v1` result or saved controlled worker envelope. It does
not contact a model provider. Query, history, expansion, and dossier commands read retained
state without making semantic provider calls. Saved worker imports and caller labels are not
live provider telemetry; provider attempts or billing are reported only when linked evidence
supports them.

The reader reports inventory coverage by unit. It checks quoted text against retained source
bytes and marks unresolved quotes and missing units visibly. A refresh keeps historical claims
and evidence, rechecks changed units, and marks claims with invalidated dependencies for review.
These checks provide traceable local state; they do not establish semantic completeness.

The existing `hakodesh קונסולטאווי ...` and `hakodesh-reader-pilot` local pilot remain
available with their existing behavior. See [0.8.1 release notes](docs/RELEASE_NOTES-0.8.1.md)
and the [reader guide](src/hakodesh/resources/reader-v2/README.md).

## עלוקווענטיא: 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* | הצהרתי: חוזה האירועים |
| אינסטיטוי | *institui* | הגדרתי ושילבתי מארח לפי חוזה מפורש |
| קונסולטאווי | *consultavi* | בחנתי מעטפת קבלה מקומית כנסוי תפקודי |

`hakodesh --help` lists the canonical command forms 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
hakodesh רעקענסוי                                      # empty-book inventory
hakodesh פערקוסי פרובאווי-קאנון --confirm              # mint a dialect-named spell
hakodesh דיקסי פרובאווי-קאנון                          # cast it; receipts land in receipts/פרובאווי-קאנון/
hakodesh אינסטיטוי claude preview                      # inspect supported Claude setup diff
hakodesh אינסטיטוי claude apply --confirm              # explicit first activation
hakodesh אינסטיטוי claude check                        # inspect installed adapter version
```

## 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 runtime depends on `platformdirs`. Its Claude adapter is bundled in the wheel and
uses the configured Claude Code settings home; it does not inspect a vault or move secrets.
`tests/test_agnostic.py` keeps the rest of the package host-neutral.

## SDK

See [docs/ONBOARDING.md](docs/ONBOARDING.md) for the update/setup journey, copy-ready
`AGENTS.md` and `CLAUDE.md` blocks, safety coverage, rollback, and trust boundary.

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