Skip to content

H3 + H4 + H5 closeout; project copyright refresh #12

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
david-w-t merged 4 commits into from
May 8, 2026
Merged

H3 + H4 + H5 closeout; project copyright refresh #12

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
c48ef92
H3: multi-parent class inheritance (BFS DAG ancestry)
david-w-t May 8, 2026
220d70e
H4 + H5: multi-class instance membership and ambiguity-detecting clas…
david-w-t May 8, 2026
39609eb
Refresh copyright headers project-wide; add NOTICE.md (SPDX, GPL-2.0-…
david-w-t May 8, 2026
3f012ba
Drop redundant 'page references' divider from dictionary_imp.erl header
david-w-t May 8, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
68 changes: 32 additions & 36 deletions ARCHITECTURE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,8 @@
<!--
Copyright (c) 2026 David W. Thomas
SPDX-License-Identifier: GPL-2.0-or-later
-->

# SeerStoneGraphDb — Architecture

> High-level shape of the system. Updated as the code's architecture changes — not as
Expand All @@ -10,23 +15,23 @@

## 1. Status

| Component | State |
| ------------------- | ------------------------------------------------------------------------------------------------------------- |
| Build | Compiles clean — zero warnings (OTP 27 / rebar3 3.24) |
| `nref` subsystem | Fully implemented; DETS-backed; `set_floor/1` API |
| `dictionary_imp` | Implemented; not yet wired to `dictionary_server` / `term_server` |
| `graphdb_bootstrap` | Implemented — Mnesia schema, table creation, scaffold loader |
| `graphdb_mgr` | Implemented — bootstrap startup, read API, category guard, cache audit/repair. Write-side delegation pending. |
| `graphdb_attr` | Implemented — attribute library (name, literal, relationship attributes) |
| `graphdb_class` | Implemented — taxonomic hierarchy (single inheritance only — see §10) |
| `graphdb_instance` | Implemented — compositional hierarchy + four-level inheritance (single class membership only — see §10) |
| `graphdb_rules` | Stub |
| `graphdb_language` | Stub |
| Tests | 186 passing (122 Common Test + 64 EUnit) |

The kernel is functional under single-class-membership / single-inheritance
semantics. Multi-inheritance, template-scoped connections, and
multilingual support are open architectural questions — see §10.
| Component | State |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| Build | Compiles clean — zero warnings (OTP 27 / rebar3 3.24) |
| `nref` subsystem | Fully implemented; DETS-backed; `set_floor/1` API |
| `dictionary_imp` | Implemented; not yet wired to `dictionary_server` / `term_server` |
| `graphdb_bootstrap` | Implemented — Mnesia schema, table creation, scaffold loader |
| `graphdb_mgr` | Implemented — bootstrap startup, read API, category guard, cache audit/repair. Write-side delegation pending. |
| `graphdb_attr` | Implemented — attribute library (name, literal, relationship attributes) |
| `graphdb_class` | Implemented — taxonomic hierarchy with multi-parent inheritance (BFS DAG walk, H3) |
| `graphdb_instance` | Implemented — compositional hierarchy + four-level inheritance with multi-class membership (H4) and ambiguity-detecting class resolver (H5) |
| `graphdb_rules` | Stub |
| `graphdb_language` | Stub |
| Tests | 209 passing (145 Common Test + 64 EUnit) |

The kernel is functional under multi-inheritance and multi-class-
membership semantics. Template features beyond the connection-arc
scope AVP (M7) and multilingual support (M6) remain open; see §10.

---

Expand Down Expand Up @@ -356,38 +361,29 @@ create, modify, or delete a `category` node.
order from [`the-knowledge-network.md`](the-knowledge-network.md) §6:

1. **Local AVPs** on the instance — highest.
2. **Class-bound values** — class itself plus its taxonomic ancestor
chain (nearest first).
2. **Class-bound values** — every class membership in
`node.classes`; for each, walk the class itself plus its taxonomic
ancestor DAG (`graphdb_class:ancestors/1`, BFS over multi-parent
classes, nearest first; H3). Per-membership hits are gathered as
`[{ClassNref, Value}]` and reduced: a single distinct value wins
(`{ok, Value}`); two or more distinct values produce
`{error, {ambiguous_class_value, AttrNref, Hits}}`; zero hits fall
through (H4 + H5).
3. **Compositional ancestors** — unbroken upward walk via the
`node.parents` cache (single-chain today; H3 will add multi-parent
DAG traversal).
`node.parents` cache. Composition is a tree (one whole has at most
one parent), so the walk is single-chain.
4. **Directly connected nodes** — `kind = connection` arcs only, one
level deep — lowest.

Each level is consulted only if higher levels returned `not_found`.

The current implementation supports single class membership; resolver
gaps for multi-class disambiguation are tracked in `TASKS-HIGH.md` H5,
which lands alongside the H4 multi-membership API.

---

## 10. Open Architectural Questions

Pending architectural decisions. Each item has a detailed task in the
severity-grouped task files.

### Multi-inheritance representation

The spec (§5) requires multiple class inheritance and multiple instance
class membership. The schema infrastructure landed in H0:
`node.parents` and `node.classes` are cache lists today, populated as
length-1 lists for the single-parent / single-class cases.
`graphdb_class:ancestors/1` and the `resolve_from_class` taxonomy walk
already traverse via arcs; remaining work is the multi-parent /
multi-class API surface and DAG semantics. See `TASKS-HIGH.md` H3, H4,
H5.

### Multilingual storage

Names are currently raw Erlang strings on every node. Spec §15 requires
Expand Down
5 changes: 5 additions & 0 deletions CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,8 @@
<!--
Copyright (c) 2026 David W. Thomas
SPDX-License-Identifier: GPL-2.0-or-later
-->

# OpenWolf

@.wolf/OPENWOLF.md
Expand Down
32 changes: 32 additions & 0 deletions NOTICE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
<!--
Copyright (c) 2008 SeerStone, Inc.
Copyright (c) 2026 David W. Thomas
SPDX-License-Identifier: GPL-2.0-or-later
-->

# NOTICE

SeerStoneGraphDb — a distributed graph database

Copyright (c) 2008 SeerStone, Inc.
Copyright (c) 2026 David W. Thomas

SPDX-License-Identifier: GPL-2.0-or-later

## Origin and continuation

The original implementation was authored by Dallas Noyes at SeerStone,
Inc. in 2008. Dallas passed away before completing the project. David
W. Thomas resumed development in 2026 to finish and extend the work,
continuing under GNU GPL v2 or later.

The knowledge model derives from US patents 5,379,366; 5,594,837; and
5,878,406 (Noyes), along with Cogito knowledge center documentation.

## License

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 2 of the License, or
(at your option) any later version. See [`LICENSE.md`](LICENSE.md) for
the full license text.
33 changes: 19 additions & 14 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,8 @@
<!--
Copyright (c) 2026 David W. Thomas
SPDX-License-Identifier: GPL-2.0-or-later
-->

# SeerStoneGraphDb

A distributed graph database written in Erlang/OTP, originally authored by
Expand All @@ -19,12 +24,12 @@ underway:
| `graphdb_bootstrap` | Fully implemented — Mnesia schema/table creation, bootstrap scaffold loader (31 nodes, 30 relationship pairs) |
| `graphdb_mgr` | Implemented — bootstrap init, public read API (`get_node`, `get_relationships`), category immutability guard, cache audit/repair (`verify_caches/0`, `rebuild_caches/0`); write operations delegate to workers |
| `graphdb_attr` | Fully implemented — attribute library (name, literal, relationship attributes, relationship types) |
| `graphdb_class` | Fully implemented — taxonomic hierarchy, qualifying characteristics, class-level inheritance |
| `graphdb_instance` | Fully implemented — compositional hierarchy, instance-to-class membership, four-level inheritance resolution |
| `graphdb_class` | Fully implemented — taxonomic hierarchy with multi-parent inheritance (BFS DAG), qualifying characteristics, class-level inheritance |
| `graphdb_instance` | Fully implemented — compositional hierarchy, multi-class membership, four-level inheritance with class-resolver ambiguity detection |
| `graphdb_rules` | Gen_server stub — deferred to Enhancements (pattern recognition, relationship constraints) |
| `graphdb_language` | Gen_server stub — next to implement (Task 6) |

**186 tests** (64 EUnit + 122 Common Test) — all passing. See
**209 tests** (64 EUnit + 145 Common Test) — all passing. See
`TASKS-HIGH.md`, `TASKS-MEDIUM.md`, and `TASKS-LOW.md` for the
prioritised task list (organised by severity).

Expand Down Expand Up @@ -226,17 +231,17 @@ Priority order — each step applies only to attributes not yet resolved by a hi
./rebar3 eunit --app=graphdb && ./rebar3 ct
```

| Suite | Type | Tests | Coverage |
| ------------------------- | ----- | ----- | --------------------------------------------------------------------------------------- |
| `graphdb_bootstrap_tests` | EUnit | 37 | Term parsing, validation, record conversion |
| `graphdb_mgr_tests` | EUnit | 9 | Direction validation, client-side arg checks |
| `graphdb_class_tests` | EUnit | 11 | `is_valid_parent_kind/1`, `collect_qc_nrefs/2` |
| `graphdb_instance_tests` | EUnit | 7 | `find_avp_value/2` |
| `graphdb_bootstrap_SUITE` | CT | 17 | Full bootstrap load, Mnesia tables, idempotency, error handling |
| `graphdb_mgr_SUITE` | CT | 23 | Bootstrap init, read ops, category guard, write stubs, cache audit/repair |
| `graphdb_attr_SUITE` | CT | 16 | Attribute create/lookup, seeding, relationship types |
| `graphdb_class_SUITE` | CT | 34 | Class create, QC, lookups, hierarchy, inheritance, templates |
| `graphdb_instance_SUITE` | CT | 32 | Instance create, relationships, lookups, hierarchy, four-level inheritance, connections |
| Suite | Type | Tests | Coverage |
| ------------------------- | ----- | ----- | ------------------------------------------------------------------------------------------------------------------------- |
| `graphdb_bootstrap_tests` | EUnit | 37 | Term parsing, validation, record conversion |
| `graphdb_mgr_tests` | EUnit | 9 | Direction validation, client-side arg checks |
| `graphdb_class_tests` | EUnit | 11 | `is_valid_parent_kind/1`, `collect_qc_nrefs/2` |
| `graphdb_instance_tests` | EUnit | 7 | `find_avp_value/2` |
| `graphdb_bootstrap_SUITE` | CT | 17 | Full bootstrap load, Mnesia tables, idempotency, error handling |
| `graphdb_mgr_SUITE` | CT | 23 | Bootstrap init, read ops, category guard, write stubs, cache audit/repair |
| `graphdb_attr_SUITE` | CT | 16 | Attribute create/lookup, seeding, relationship types |
| `graphdb_class_SUITE` | CT | 44 | Class create, QC, lookups, hierarchy, multi-inheritance (H3), inheritance, templates |
| `graphdb_instance_SUITE` | CT | 45 | Instance create, relationships, lookups, hierarchy, four-level inheritance, connections, multi-class membership (H4 + H5) |

Each CT test case runs in an isolated Mnesia database with a fresh nref
allocator in a private temp directory.
Expand Down
Loading
Loading