Phase 8: Protocol System — defprotocol, extend-type, extend-protocol, satisfies?
- types.janet: type-registry, register-protocol-method, find-protocol-method, type-satisfies? - core.janet: rewritten protocol macros (defprotocol, extend-type, extend-protocol, reify) Protocol value stores :jolt/type :jolt/protocol with :methods map Method dispatch fns use fn* [this & rest-args] → protocol-dispatch special form - evaluator.janet: protocol-dispatch, register-method, make-reified special forms satisfies? special form with type registry lookup special-symbol? entries for all 3 protocol ops + satisfies? - 4 test sections (35-38): defprotocol, extend-type, extend-protocol, satisfies? extend-type: basic dispatch works (42 constant), .-field accessor needs further debug satisfies?: fully functional with type registry - 315 ok, 2 fail (pre-existing, unchanged)
This commit is contained in:
Yogthos
parent
09c4cb2242
commit
053ed4f790
11 changed files with 463 additions and 134 deletions
|
|
@ -1,35 +1,32 @@
|
|||
{
|
||||
"jolt-dev": {
|
||||
"jolt-persistent-structures": {
|
||||
"created_by": "agent",
|
||||
"use_count": 34,
|
||||
"view_count": 49,
|
||||
"patch_count": 41,
|
||||
"last_used_at": "2026-06-03T03:03:32.578112+00:00",
|
||||
"last_viewed_at": "2026-06-03T03:03:32.570889+00:00",
|
||||
"last_patched_at": "2026-06-03T01:14:59.915995+00:00",
|
||||
"created_at": "2026-06-01T21:26:06.614465+00:00",
|
||||
"use_count": 1,
|
||||
"view_count": 7,
|
||||
"patch_count": 0,
|
||||
"last_used_at": "2026-06-03T03:49:43.520839+00:00",
|
||||
"last_viewed_at": "2026-06-03T04:18:13.482762+00:00",
|
||||
"created_at": "2026-06-03T03:35:04.130959+00:00",
|
||||
"state": "active",
|
||||
"pinned": false
|
||||
},
|
||||
"jolt-bootstrap": {
|
||||
"jolt-gotchas": {
|
||||
"created_by": "agent",
|
||||
"use_count": 9,
|
||||
"view_count": 24,
|
||||
"patch_count": 10,
|
||||
"last_used_at": "2026-06-02T18:45:23.336653+00:00",
|
||||
"last_viewed_at": "2026-06-02T21:03:17.876094+00:00",
|
||||
"last_patched_at": "2026-06-02T03:44:45.935676+00:00",
|
||||
"created_at": "2026-06-01T21:49:51.101718+00:00",
|
||||
"use_count": 0,
|
||||
"view_count": 5,
|
||||
"patch_count": 0,
|
||||
"last_viewed_at": "2026-06-03T04:18:13.476736+00:00",
|
||||
"created_at": "2026-06-03T03:50:41.474730+00:00",
|
||||
"state": "active",
|
||||
"pinned": false
|
||||
},
|
||||
"jolt-compiler": {
|
||||
"created_by": "agent",
|
||||
"use_count": 7,
|
||||
"view_count": 11,
|
||||
"use_count": 9,
|
||||
"view_count": 19,
|
||||
"patch_count": 9,
|
||||
"last_used_at": "2026-06-03T03:02:46.825298+00:00",
|
||||
"last_viewed_at": "2026-06-03T03:02:46.818525+00:00",
|
||||
"last_used_at": "2026-06-03T03:49:43.470444+00:00",
|
||||
"last_viewed_at": "2026-06-03T04:18:13.465606+00:00",
|
||||
"last_patched_at": "2026-06-03T03:03:27.524946+00:00",
|
||||
"created_at": "2026-06-02T17:54:38.690279+00:00",
|
||||
"state": "active",
|
||||
|
|
@ -38,11 +35,35 @@
|
|||
"jpm-build": {
|
||||
"created_by": "agent",
|
||||
"use_count": 0,
|
||||
"view_count": 15,
|
||||
"view_count": 21,
|
||||
"patch_count": 0,
|
||||
"last_viewed_at": "2026-06-02T21:03:17.897587+00:00",
|
||||
"last_viewed_at": "2026-06-03T04:18:13.488874+00:00",
|
||||
"created_at": "2026-06-01T20:56:39.144222+00:00",
|
||||
"state": "active",
|
||||
"pinned": false
|
||||
},
|
||||
"jolt-dev": {
|
||||
"created_by": "agent",
|
||||
"use_count": 35,
|
||||
"view_count": 56,
|
||||
"patch_count": 42,
|
||||
"last_used_at": "2026-06-03T03:49:43.510599+00:00",
|
||||
"last_viewed_at": "2026-06-03T04:18:13.470424+00:00",
|
||||
"last_patched_at": "2026-06-03T03:34:09.007253+00:00",
|
||||
"created_at": "2026-06-01T21:26:06.614465+00:00",
|
||||
"state": "active",
|
||||
"pinned": false
|
||||
},
|
||||
"jolt-bootstrap": {
|
||||
"created_by": "agent",
|
||||
"use_count": 9,
|
||||
"view_count": 30,
|
||||
"patch_count": 10,
|
||||
"last_used_at": "2026-06-02T18:45:23.336653+00:00",
|
||||
"last_viewed_at": "2026-06-03T04:18:13.459884+00:00",
|
||||
"last_patched_at": "2026-06-02T03:44:45.935676+00:00",
|
||||
"created_at": "2026-06-01T21:49:51.101718+00:00",
|
||||
"state": "active",
|
||||
"pinned": false
|
||||
}
|
||||
}
|
||||
|
|
@ -1,4 +1,5 @@
|
|||
# jolt-dev
|
||||
# jolt-dev
|
||||
|
||||
Jolt development workflow — build, test, special form patterns, Janet gotchas
|
||||
|
||||
|
|
@ -13,82 +14,63 @@ jpm test # runs all tests
|
|||
janet test/foo.janet # run a single test file from project root
|
||||
```
|
||||
|
||||
## Janet Eval Pipeline (critical)
|
||||
## Special Form Checklist
|
||||
|
||||
Janet's `(parse s)` does NOT return a parsed form — it returns `[symbol, error-position]`.
|
||||
For evaluating Janet source strings, use the parser pipeline:
|
||||
To add a new special form to the evaluator:
|
||||
|
||||
1. Add the name to `special-symbol?` in `src/jolt/evaluator.janet`
|
||||
2. Add a match arm in `eval-list` (the match on `name`)
|
||||
3. Add tests in `test/evaluator-test.janet`
|
||||
|
||||
The match arm receives `ctx`, `bindings`, and `form` (the full list). Use `(in form 1)` for first arg, etc.
|
||||
|
||||
**Non-symbol heads** (keywords, etc.): `eval-list` first checks `(and (struct? first-form) (= :symbol (...)))` before extracting `name`. If not a symbol, falls through to default function application.
|
||||
|
||||
### Current special forms (29):
|
||||
`quote`, `syntax-quote`, `unquote`, `unquote-splicing`, `do`, `if`, `def`, `defmacro`, `fn*`, `let*`, `loop*`, `recur`, `throw`, `try`, `set!`, `var`, `locking`, `instance?`, `defmulti`, `defmethod`, `deftype`, `new`, `.`, `var-get`, `var-set`, `var?`, `alter-var-root`, `find-var`, `intern`, `alter-meta!`, `reset-meta!`, `disj`, `set?`
|
||||
|
||||
## Compiler Architecture
|
||||
|
||||
Two-phase: `analyze-form [form bindings ctx]` → `emit-ast` (string) or `emit-expr` (data structures).
|
||||
|
||||
**Why data structures:** Janet's `eval` can't see `use`-imported symbols. Embed function VALUES directly via `core-fn-values` table.
|
||||
|
||||
**eval-string dispatch** (compile mode): stateful forms → interpreter; everything else → `compile-and-eval`. Macros expand at analyze time.
|
||||
|
||||
## PersistentHashMap Gotchas
|
||||
|
||||
- `core-map?`: `(if (and (table? x) (get x :jolt/deftype)) true false)` — `and` returns last truthy, not boolean
|
||||
- `core-count`: subtract 1 for deftype tables (skip `:jolt/deftype` key)
|
||||
- Equality: convert via `phm-to-struct` before `deep=`
|
||||
|
||||
## defrecord / deftype Patterns
|
||||
|
||||
- defrecord emits `(deftype TypeName [fields])` + arrow factory `(fn fields-vec (TypeName. field1 field2...))`
|
||||
- Records are tables with `:jolt/deftype` = type name string
|
||||
- `set!` field mutation: `(set! (.-x obj) val)` parses as array with `.-x` symbol head — check symbol name before dispatch
|
||||
|
||||
## Binding Macro
|
||||
|
||||
Uses `array-map` (plain Janet struct) not `hash-map` (PHM) to avoid PHM get() incompatibility with `var-get`.
|
||||
|
||||
## Tagged Literals (#inst, #uuid)
|
||||
|
||||
`:#inst` is invalid Janet keyword syntax (contains `#`). Use dynamic table construction:
|
||||
```janet
|
||||
(def p (parser/new))
|
||||
(parser/consume p source)
|
||||
(parser/eof p) # REQUIRED — otherwise produce returns nil
|
||||
(def form (parser/produce p))
|
||||
(eval form)
|
||||
(let [dr @{}] (put dr (keyword "#inst") (fn [s] s)) dr)
|
||||
```
|
||||
|
||||
**Never** try `(eval [if true 1 2])` — Janet's `eval` doesn't recognize special forms in tuple data structures.
|
||||
## LazySeq Patterns
|
||||
|
||||
## `var` vs `def`
|
||||
|
||||
When you need to mutate a local with `set`, use `(var x nil)` not `(def x nil)`. `def` creates constants.
|
||||
|
||||
## Compiler (see also `jolt-compiler` skill)
|
||||
|
||||
`src/jolt/compiler.janet` — Clojure→Janet source compiler with macro expansion.
|
||||
`test/compiler-test.janet` — 11 test groups covering all ops.
|
||||
|
||||
Key design decision: **compile-and-eval emits Janet DATA STRUCTURES, not source strings**, because Janet's `eval` doesn't see `use`-imported symbols. `core-fn-values` table resolves Janet names to actual function values at compile time.
|
||||
|
||||
### Adding a compiled op
|
||||
|
||||
1. **analyze-form**: add `match head-name` arm returning `{:op :your-op ...}`
|
||||
2. **emit-ast**: add str function + `:your-op` case in `set emit-ast` dispatch
|
||||
3. **emit-expr**: add expr function + `:your-op` case in `set emit-expr` dispatch
|
||||
4. Add tests in `test/compiler-test.janet`
|
||||
|
||||
### Emit-expr critical rules
|
||||
- **Vectors**: wrap with `['tuple ...]` — bare tuples eval as fn calls
|
||||
- **try/catch**: `[(tuple ;[err-sym]) handler]` NOT `(catch [err] body)`
|
||||
- **quote**: use `raw-form->janet` converter, don't re-analyze
|
||||
- **Core fns**: resolve via `core-fn-values` table, embed fn VALUES not names
|
||||
|
||||
### Macro expansion
|
||||
`analyze-form` checks `resolve-macro` first — if head is a macro var, applies fn, re-analyzes expanded form (only when ctx passed).
|
||||
|
||||
## Persistent Data Structures
|
||||
|
||||
Located in:
|
||||
- `src/jolt/clojure/lang/persistent_vector.clj`
|
||||
- `src/jolt/clojure/lang/persistent_hash_map.clj`
|
||||
|
||||
Loaded at init time by `load-persistent-structures` in `api.janet`. Use `{:mutable? true}` to skip and use Janet-native types.
|
||||
|
||||
### Implementation detail
|
||||
Simple array-based implementation (node-assoc/node-find/find-key-index), NOT HAMT bit-trie.
|
||||
HAMT failed because Janet uses 64-bit doubles and bit operations require 32-bit signed ints.
|
||||
- Use `indexed?` not `tuple?` for realized sequences (may be arrays from `cons`/`concat`)
|
||||
- Avoid `val'` (apostrophe in symbol names) — causes Janet parse errors; use `vf` instead
|
||||
- `ls-first`/`ls-rest`/`ls-seq` all call `realize-ls` first (caches result, realizes once)
|
||||
|
||||
## Janet Gotchas
|
||||
|
||||
- Bit operations (brshift, brushift, band) use 32-bit signed integers. Hash values can exceed 32-bit range. Use `(band x 0xFFFFFFFF)` before shifting.
|
||||
- `deftype` creates tables, not structs. `struct?` returns false.
|
||||
- `(get child :key)` DOES follow table prototype chain — resolved and confirmed working.
|
||||
- Janet LSP produces many false positives on `.janet` files — safe to ignore.
|
||||
- Janet `and` returns the last truthy value, NOT boolean `true`. Wrap with `(if (and ...) true false)` for predicates.
|
||||
- `set!` field mutation: `(set! (.-x obj) val)` reader creates `(. -x obj)` array — must check for `.` head in set! handler BEFORE the var mutation branch.
|
||||
|
||||
## deftype/defrecord Patterns
|
||||
|
||||
**deftype** produces a table with `:jolt/deftype` key (format: `"ns.TypeName"`):
|
||||
- Constructor: `(TypeName. args...)` — evaluator creates `@{:jolt/deftype "ns.TypeName" :key1 val1 ...}`
|
||||
- Field access: `(. obj field)` — evaluator does `(get obj (keyword field-name))`
|
||||
- Mutation: `(set! (.-field obj) val)` — reader creates `(. -field obj)` array form
|
||||
|
||||
**Defrecord** macro emits `(do (deftype Name [fields]) (def ->Name ...) (def map->Name ...))`.
|
||||
|
||||
**core-map?** for records: `(or (phm? x) (struct? x) (if (and (table? x) (get x :jolt/deftype)) true false))`
|
||||
|
||||
**core-count** for records: `(- (length (keys coll)) 1)` (skip `:jolt/deftype` key)
|
||||
|
||||
## Symbol representation
|
||||
|
||||
Jolt symbols are `{:jolt/type :symbol :ns <string-or-nil> :name <string>}` as produced by the reader.
|
||||
- `def` creates constants; use `(var x nil)` for mutable locals
|
||||
- Bare tuples in `eval` are function calls: `[1 2 3]` tries to call `1`. Use `['tuple 1 2 3]`
|
||||
- `try` format: `(try body ([err] handler))` NOT `(try body (catch sym handler))`
|
||||
- core-renames MUST match actual fn names: `"-"` → `"core-sub"` (not `"core--"`)
|
||||
- Janet `parse` vs `parser/new`: use `parser/new` + `parser/consume` + `parser/eof` + `parser/produce` for full source parsing
|
||||
- `(break val)` breaks from a while loop returning val — useful in bucket search patterns
|
||||
45
.dirge/skills/jolt-gotchas/SKILL.md
Normal file
45
.dirge/skills/jolt-gotchas/SKILL.md
Normal file
|
|
@ -0,0 +1,45 @@
|
|||
---
|
||||
name: jolt-gotchas
|
||||
description: Common pitfalls and workarounds discovered during Jolt implementation
|
||||
---
|
||||
|
||||
# jolt-gotchas
|
||||
|
||||
Recurring pitfalls and their fixes discovered across all implementation phases.
|
||||
|
||||
## PHM/Set Metadata Key Leakage
|
||||
|
||||
PHM and set internal keys (`:jolt/deftype`, `:cnt`, `:buckets`, `:_meta`, `:jolt/type`, `:phm`) leak into `pairs`/`keys` iteration. Must filter in merge, merge-with, keys, vals, and print-collection.
|
||||
|
||||
```janet
|
||||
(when (and (not= k :jolt/deftype) (not= k :cnt)
|
||||
(not= k :buckets) (not= k :_meta)
|
||||
(not= k :jolt/type) (not= k :phm)) ...)
|
||||
```
|
||||
|
||||
## Keywords with `#` Are Invalid Janet Literals
|
||||
|
||||
`:#inst`, `:#uuid` cause parse errors. Use dynamic table construction:
|
||||
```janet
|
||||
(let [dr @{}] (put dr (keyword "#inst") fn) dr)
|
||||
```
|
||||
|
||||
## Janet `break` Only Works in Loops
|
||||
|
||||
Does NOT work inside `let`. Use `(var found nil)` + `(set found val) (break)` pattern.
|
||||
|
||||
## Bare Tuples in `eval` Are Function Calls
|
||||
|
||||
`(eval [1 2 3])` calls `1` as function. Use `['tuple 1 2 3]` in data-structure emitter.
|
||||
|
||||
## Janet `case` for Multi-Arity
|
||||
|
||||
Janet lacks Clojure-style multi-arity defn. Use `(defn f [& args] (case (length args) 1 ... 2 ...))`.
|
||||
|
||||
## core-renames + core-fn-values Must Stay in Sync
|
||||
|
||||
Both tables must be updated together when adding core fns. Missing entries = silent nil returns. `"-"` is `core-sub` NOT `core--`.
|
||||
|
||||
## `set!` Field Mutation Reader Quirk
|
||||
|
||||
`(set! (.-x obj) val)` parses as array with `.-x` symbol head — not as standalone `.-x` symbol. Check for this case before the `(. obj -field)` shorthand.
|
||||
72
.dirge/skills/jolt-persistent-structures/SKILL.md
Normal file
72
.dirge/skills/jolt-persistent-structures/SKILL.md
Normal file
|
|
@ -0,0 +1,72 @@
|
|||
---
|
||||
name: jolt-persistent-structures
|
||||
description: PersistentHashMap, PersistentHashSet, and LazySeq implementation patterns in Janet tables
|
||||
---
|
||||
|
||||
# jolt-persistent-structures
|
||||
|
||||
PersistentHashMap, PersistentHashSet, and LazySeq implementation patterns in Janet tables.
|
||||
|
||||
## PersistentHashMap
|
||||
|
||||
Bucket-based immutable hash map using copy-on-write. Stores data in `:buckets` (array of flat `[k v k v ...]` bucket arrays), `:cnt` (entry count), `:jolt/deftype` type tag, and `:_meta`.
|
||||
|
||||
### Core functions (in phm.janet)
|
||||
- `make-phm [& kvs]` — create from key-value pairs
|
||||
- `phm-get [m k &opt default]` — lookup with optional default
|
||||
- `phm-assoc [m k v]` — return new map with k→v
|
||||
- `phm-dissoc [m k]` — return new map without k
|
||||
- `phm-contains? [m k]` — membership check
|
||||
- `phm-count [m]` — number of entries
|
||||
- `phm-to-struct [m]` — convert to Janet struct (for equality, keys, vals)
|
||||
- `phm-entries [m]` — return `[[k v] ...]` pairs
|
||||
|
||||
### Core function integration (core.janet)
|
||||
Each core fn checks `phm?` first, then falls through to struct/table logic:
|
||||
- `core-get` → `phm-get`
|
||||
- `core-assoc` → `phm-assoc`
|
||||
- `core-dissoc` → `phm-dissoc`
|
||||
- `core-contains?` → `phm-contains?`
|
||||
- `core-count` → `phm-count`
|
||||
- `core-keys/vals/seq` → via `phm-to-struct`
|
||||
- `core-merge/merge-with` → PHM-aware iteration
|
||||
- `core-empty?` → check `:cnt = 0`
|
||||
- `core-conj` → `phm-assoc` for `[k v]` pairs
|
||||
|
||||
### Gotchas
|
||||
- `core-map?`: `(if (and (table? x) (get x :jolt/deftype)) true false)` — `and` returns last truthy
|
||||
- `core-count`: subtract 1 for deftype tables
|
||||
- Equality: `phm-to-struct` → `deep=`
|
||||
- `core-hash-map` wraps `make-phm`, so all literal maps become PHMs
|
||||
|
||||
## PersistentHashSet
|
||||
|
||||
Backed by a PersistentHashMap with sentinel `true` values.
|
||||
|
||||
### Core functions (in phm.janet)
|
||||
- `make-phs [& xs]` — create from items
|
||||
- `phs-conj [s & xs]` — add items (idempotent)
|
||||
- `phs-disj [s & xs]` — remove items
|
||||
- `phs-contains? [s x]` — membership
|
||||
- `phs-count [s]` — cardinality
|
||||
- `phs-seq [s]` — keys as tuple
|
||||
- `phs-get [s x &opt default]` — returns x if present
|
||||
- `phs-to-struct [s]` — convert for equality via `deep=`
|
||||
|
||||
### Special forms (evaluator.janet)
|
||||
- `:jolt/set` handler: `(apply make-phs (form :value))`
|
||||
- `"disj"` dispatch — validates set?, calls `phs-disj`
|
||||
- `"set?"` dispatch — calls `set?` predicate
|
||||
|
||||
## LazySeq
|
||||
|
||||
Realize-once thunk wrapper.
|
||||
|
||||
### Core functions (in phm.janet)
|
||||
- `make-lazy-seq [thunk]` — create from thunk
|
||||
- `realize-ls [ls]` — force + cache (recursive)
|
||||
- `ls-first/ls-rest/ls-seq/ls-count`
|
||||
|
||||
### Gotchas
|
||||
- Use `indexed?` not `tuple?` for realized sequences
|
||||
- Avoid `val'` (parse error), use `vf`
|
||||
Loading…
Add table
Add a link
Reference in a new issue