Skip to content
BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

5 Commits
.gitbucket
.gitbucket
 
 
.github
.github
 
 
external
external
 
 
schemas
schemas
 
 
skills
skills
 
 
src
src
 
 
tests
tests
 
 
.gitignore
.gitignore
 
 
Cargo.lock
Cargo.lock
 
 
Cargo.toml
Cargo.toml
 
 
README.md
README.md
 
 

Repository files navigation

SnapKitty GitBucket

Git as WORM, JSON as Query, Prolog as Truth

Deterministic memory layer for sovereign compute stacks. Every git commit produces an immutable, WORM-sealed (Write-Once-Read-Many) memory bucket with Ed25519 cryptographic provenance. Rust binary CLI with a Prolog runtime for multi-dimensional indexing and proof-carrying queries.

╔══════════════════════════════════════════════════════════╗
║              SNAPKITTY GITBUCKET v0.1.0                  ║
║          DETERMINISTIC MEMORY LAYER FOR AGENT OS         ║
╠══════════════════════════════════════════════════════════╣
║  GIT  = WORM        Every commit is one immutable write  ║
║  JSON = QUERY       Buckets are JSON; query is indexing  ║
║  PROLOG = TRUTH     Runtime fact base with proof chains  ║
║  SEAL = Ed25519     WORM seals for tamper evidence      ║
╚══════════════════════════════════════════════════════════╝

Table of Contents

  1. Quick Start
  2. Architecture Overview
  3. CLI Reference
  4. Memory Bucket Schema
  5. Extractor Pipeline
  6. Rust API Reference
  7. Prolog Runtime
  8. Multi-Dimensional Index
  9. Trust Model
  10. WORM Sealing & Ed25519
  11. Skill Registry
  12. Skill Artifacts
  13. Skills Scripts (15)
  14. QWEN Skill Packets (19)
  15. Plans (7)
  16. Surveys (3)
  17. External Crates
  18. Testing
  19. Five Invariants
  20. Integration Guide
  21. Agent Directives
  22. License

Quick Start

# 1. Build the binary (Rust nightly or stable 2021 edition)
cargo build --release

# 2. Extract memory buckets from current git repo (converts git log → JSON buckets)
./target/release/gitbucket extract --repo .

# 3. Verify all WORM seals in bucket directory
./target/release/gitbucket verify

# 4. Query the memory index by topic
./target/release/gitbucket query --field topic --value authentication

# 5. Query by agent
./target/release/gitbucket query --field agent --value "SnapKitty"

# 6. Generate new Ed25519 keypair
./target/release/gitbucket keygen

# 7. Backfill full git history
./target/release/gitbucket backfill --repo . --to HEAD

# 8. With Prolog runtime:
swipl -g "compile_extractors" -t halt                          # compile extractors
swipl -g "index:load_buckets('.gitbucket/buckets')" -t halt    # load index
swipl -g "query:assemble_context(_{topic:'auth'}, _)" -t halt  # query

Prerequisites

Dependency Version Purpose
Rust 2021 edition (≥1.65) CLI binary and libraries
SWI-Prolog ≥9.0 Extractor and index runtime
Node.js ≥18 Skill WASM shims & verify scripts
Python 3 ≥3.10 AXIOM kernel, mathematical verifiers

Architecture Overview

Topology

┌──────────────────────────────────────────────────────────────────┐
│                        AGENT / HUMAN INTERFACE                     │
│  gitbucket extract | verify | query | keygen | backfill (CLI)      │
│  swipl query.pl   │ HTTP API for proof-carrying context bundles    │
└──────────────────────────────────────────────────────────────────┘
                               │
                               ▼
┌──────────────────────────────────────────────────────────────────┐
│              QUERY LAYER  (query.pl + planner.rs)                  │
│   assemble_context(Spec, Bundle)  →  ranked, token-budgeted       │
│   audit trail: {query, buckets, verifier, timestamp, count}       │
└──────────────────────────────────────────────────────────────────┘
                               │
                               ▼
┌──────────────────────────────────────────────────────────────────┐
│           MULTI-DIMENSIONAL INDEX  (index.pl + index.rs)           │
│  ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐  │
│  │ file │ │entity│ │topic │ │agent │ │ time │ │ type │ │ dep  │  │
│  └──────┘ └──────┘ └──────┘ └──────┘ └──────┘ └──────┘ └──────┘  │
└──────────────────────────────────────────────────────────────────┘
                               │
                               ▼
┌──────────────────────────────────────────────────────────────────┐
│           EXTRACTION PIPELINE  (extract.rs + extractors/*.pl)      │
│                                                                     │
│  git log ──► commit_message_parser ──► diff_analyzer ──►           │
│             entity_linker ──► trust_evaluator ──► MemoryBucket      │
│                                                                     │
│  Determinism invariant: same input + same extractor version         │
│  → bit-identical JSON output                                        │
└──────────────────────────────────────────────────────────────────┘
                               │
                               ▼
┌──────────────────────────────────────────────────────────────────┐
│           WORM STORAGE  (buckets/*.json + seals/*.sig)             │
│                                                                     │
│  Every bucket:                                                     │
│    {id, git_hash, parent_hash, files[], worm_seal, ...}            │
│    Sealed with Ed25519 over SHA-256(id:git_hash:timestamp)         │
│    Immutable once written. Tamper-evident via chain hashes.        │
└──────────────────────────────────────────────────────────────────┘

Data Flow (Mermaid)

graph TB
    subgraph INPUT["Git Repository"]
        G[git log --format]
        D[git diff --stat]
    end

    subgraph EXTRACT["Extraction Pipeline (deterministic)"]
        CMP[commit_message_parser.pl<br/>type(scope): summary]
        DA[diff_analyzer.pl<br/>files[], roles]
        EL[entity_linker.pl<br/>entities, symbols]
        TE[trust_evaluator.pl<br/>trust level]
    end

    subgraph INDEX["Multi-Dimensional Index"]
        I1[by_file]
        I2[by_entity]
        I3[by_topic]
        I4[by_agent]
        I5[by_time]
        I6[by_type]
        I7[by_dep]
    end

    subgraph QUERY["Proof-Carrying Query"]
        Q[assemble_context/2]
        TS[topological_sort]
        TB[token-budget filter]
        AT[audit trail]
    end

    subgraph STORAGE["WORM Storage"]
        BJ[buckets/*.json]
        PG[Plasma Gate<br/>Ed25519 sign]
    end

    G --> CMP
    D --> DA
    CMP --> EL
    DA --> EL
    CMP --> TE
    EL --> TE
    TE --> STORAGE
    STORAGE --> INDEX
    INPUT --> QUERY
    INDEX --> Q
    Q --> TS
    TS --> TB
    TB --> AT
Loading

Dependency Graph

graph LR
    subgraph RUST["Rust Crate (binary)"]
        main[main.rs] --> bucket[bucket.rs]
        main --> extractor[extractor.rs]
        main --> index[index.rs]
        main --> planner[planner.rs]
        main --> schema[schema.rs]
        main --> seal[seal.rs]
        lib[lib.rs] --> bucket
        lib --> extractor
        lib --> index
        lib --> planner
        lib --> seal
        lib --> schema
    end

    subgraph PROLOG["Prolog Runtime"]
        config[config.pl] --> extractors
        extractors --> commit_m[commit_message_parser.pl]
        extractors --> diff[diff_analyzer.pl]
        extractors --> entity[entity_linker.pl]
        extractors --> trust[trust_evaluator.pl]
        index_pl[index.pl] --> memory_bucket/1
        query_pl[query.pl] --> index_pl
        plasma[plasma_gate.pl] --> query_pl
    end

    subgraph EXTERNAL["External Crates"]
        sp[sovereign-prism]
        sr[sovereign-ruby]
    end

    RUST --> PROLOG
    PROLOG --> EXTERNAL
Loading

CLI Reference

The gitbucket binary exposes five subcommands via clap:

extract

Convert git commits to memory buckets. Reads git log --format=%H|%P|%an|%ae|%ai|%s and git diff --stat for each commit.

gitbucket extract --repo <PATH> [--from <REF>] [--to <REF>] [--output <DIR>]

  --repo    Path to git repository        [default: "."]
  --from    Start commit (ref or hash)    [optional]
  --to      End commit (ref or hash)      [default: HEAD]
  --output  Output directory for buckets  [default: ".gitbucket/buckets"]

Output: One mem_NNNNNN.json per commit in the output directory.

verify

Verify all WORM seals in a bucket directory. Checks Ed25519 signatures on every bucket.

gitbucket verify [--buckets <DIR>]

  --buckets  Bucket directory  [default: ".gitbucket/buckets"]

Output: count of passed/failed seals.

query

Query the in-memory multi-dimensional index built from bucket files. Returns a ContextBundle with audit trail.

gitbucket query --field <FIELD> --value <VALUE> [--budget <N>]

  --field   Query dimension: topic | file | entity | agent | type
  --value   Query value to match
  --budget  Token budget for response  [default: 8000]

Output: JSON ContextBundle with bucketed results sorted by rank within token budget.

keygen

Generate Ed25519 keypair for WORM sealing.

gitbucket keygen

Output: Public key (ed25519:...) and private key (ed25519:...).

backfill

Extract a range of git history into buckets (convenience alias for extract with fixed output dir).

gitbucket backfill --repo <PATH> [--from <REF>] --to <REF>

  --repo  Path to git repository  [default: "."]
  --from  Start commit            [optional]
  --to    End commit              [default: HEAD]

Memory Bucket Schema

Structure (src/bucket.rs)

Every git commit produces exactly one MemoryBucket:

{
  "id": "mem_000001",
  "git_hash": "a8d72e4f1b3c5e7d9f0a2b4c6d8e0f1a3b5c7d9e",
  "parent_hash": "19fd33a1b2c4d6e8f0a2b4c6d8e0f1a3b5c7d9e",
  "timestamp": "2026-07-02T18:45:00Z",
  "author": {
    "id": "SnapKitty",
    "pubkey": "ed25519:a8d72e4f1b3c5e7d9f0a2b4c6d8e0f1a3b5c7d9e"
  },
  "branch": "main",
  "type": "implementation",
  "summary": "auth: add Ed25519 verification",
  "keywords": ["auth", "ed25519", "verification"],
  "entities": ["seal", "auth", "verifier"],
  "files": [
    {
      "path": "src/seal.rs",
      "role": "core",
      "diff_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
    }
  ],
  "related": ["issue_42"],
  "trust": "verified",
  "immutable": true,
  "worm_seal": {
    "algorithm": "Ed25519",
    "signature": "a8d72e...128-hex-chars...",
    "signer": "Plasma_Gate",
    "audit_ref": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Fields

Field Type Description
id string Format mem_NNNNNN, auto-incremented
git_hash string Full SHA-1 commit hash (40 hex chars)
parent_hash string Parent commit hash (or empty for genesis)
timestamp string ISO 8601 datetime of commit
author object {id: string, pubkey: string} with Ed25519 public key
branch string Git branch name resolved at extraction time
type string One of 6 valid types (see schema)
summary string Structured commit summary from conventional commit
keywords string[] Extracted from summary + scope, stop-word filtered
entities string[] Named entities from file paths + summary
files FileEntry[] Files changed in commit with role and diff_hash
related string[] Related issue/PR references parsed from Refs:
trust string verified
immutable boolean Always true — buckets are write-once
worm_seal object Ed25519 signature payload

Valid Types (src/schema.rs)

Type Conventional Commit Prefix
architecture docs:, style:, build:
implementation feat:, refactor:, perf:
decision decision:
repair fix:, revert:
audit test:, ci:, chore:, security:
fiscal_decision fiscal:

Valid File Roles

core, new, modified, deleted, config, test, doc

JSON Schema (schemas/memory-bucket-v1.json)

Full JSON Schema with additionalProperties: false validation, pattern constraints on id (^mem_[0-9]{6}$), git_hash (^[a-f0-9]{40}$), diff_hash (^[a-f0-9]{64}$), and enum constraints on type and trust.

Extractor Pipeline

Pipeline Stages

git log ──┬──► commit_message_parser.pl ───────┬──► MemoryBucket
          │    (type, summary, keywords,        │
          │     related, breaking flag)          │
          │                                      │
          ├──► diff_analyzer.pl ─────────────────┤
          │    (files[], roles, diff_hash)       │
          │                                      │
          ├──► entity_linker.pl ─────────────────┤
          │    (entities from paths + summary)   │
          │                                      │
          └──► trust_evaluator.pl ───────────────┘
               (trust level from signer,
                branch policy, breaking changes)

1. commit_message_parser.pl (187 lines)

Parses conventional commit format: type(scope): summary\n\nbody\nRefs: #123

Lines 16-44: Module header and main parse_commit_message/2 predicate returning a dict with type, summary, keywords, related, trust, breaking.

Lines 46-65: parse_first_line/4 — regex matches type(scope): summary or type: summary, falls back to chore type.

Lines 67-88: parse_body/5 — scans for BREAKING CHANGE:, BREAKING:, Refs:, Ref: lines, extracts keywords.

Lines 92-107: classify_type/2 — maps 14 conventional commit types (feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert, security, decision, audit, fiscal) to 6 bucket types.

Lines 109-164: Helpers: extract_scope/2, extract_keywords/2, extract_refs/2, has_breaking_change/1, stop-word filtering (78 English stop words).

2. diff_analyzer.pl (99 lines)

Parses git diff --stat output into structured FileEntry[].

Lines 21-24: analyze_diff/2 — splits on newlines, filters file lines (lines containing | and digits).

Lines 26-62: file_role/2 — 12 pattern-matching rules classifying files:

  • core: .rs, .cpp, .hs, .lean in src/
  • test: tests/, *_test.rs, *_test.cpp, *.test.*
  • doc: .md, .txt
  • config: Cargo.toml, CMakeLists.txt, .json, .toml, .yml, .yaml, .pl
  • Fallback: modified

Lines 64-82: diff_hash/2 (SHA-256 placeholder) and parse_file_line/2 with regex extraction.

3. entity_linker.pl (59 lines)

Extracts named entities from file paths and commit summary text.

  • file_to_entity/2: extracts stem from filename (e.g., src/engine/scheduler.rs → scheduler)
  • summary_to_entities/2: extracts capitalized words >2 chars as entity references
  • link_entity/2: looks up entity in index for cross-referencing
  • symbol_table/2: stub for Rust source symbol extraction

4. trust_evaluator.pl (62 lines)

Multi-factor trust level computation.

  • Factor 1: Signer trust — is the Ed25519 signer in trusted_keys?
  • Factor 2: Branch policy — main = verified, develop = pending, _ = pending
  • Factor 3: Breaking changes — if BREAKING CHANGE: present → pending
  • Combinator: most restrictive wins (disputed > pending > verified)
  • Stub: verify_signature/2 (production would call native Ed25519 via WASM)

Determinism Guarantee

Each extractor declares a version in config.pl:

extractor_version(commit_message_parser, '1.0.0').
extractor_version(diff_analyzer, '1.0.0').
extractor_version(entity_linker, '1.0.0').
extractor_version(trust_evaluator, '1.0.0').

Same input + same version = bit-identical output. No randomness, no floating point, no system calls.

Rust Extractor (src/extractor.rs, 271 lines)

The Rust extract_range() function:

  1. Runs git log --format=%H|%P|%an|%ae|%ai|%s over the commit range
  2. For each commit, runs git diff --stat on hash~1..hash
  3. Parses conventional commit messages with parse_conventional_commit() (same logic as the Prolog version)
  4. Classifies file roles with classify_file_role() (Rust pattern matching)
  5. Extracts entities from file stems with extract_entities_from_files()
  6. Creates MemoryBucket with pending trust and empty signature
  7. Filters 49 English stop words from keywords

File role classification maps: .rs, .cpp, .hs, .lean → core or test; .md, .txt → doc; .toml, .json, .yml, .yaml, .pl → config; .new → new; else → modified.

Rust API Reference

src/lib.rs (6 lines)

Module re-exports: bucket, extractor, index, planner, schema, seal.

src/bucket.rs (42 lines)

Core structs:

pub struct MemoryBucket {
    pub id: String,
    pub git_hash: String,
    pub parent_hash: String,
    pub timestamp: String,
    pub author: Author,
    pub branch: String,
    pub bucket_type: String,     // "type" in JSON
    pub summary: String,
    pub keywords: Vec<String>,
    pub entities: Vec<String>,
    pub files: Vec<FileEntry>,
    pub related: Vec<String>,
    pub trust: String,
    pub immutable: bool,
    pub worm_seal: WormSeal,
}

pub struct Author {
    pub id: String,
    pub pubkey: String,          // "ed25519:..."
}

pub struct FileEntry {
    pub path: String,
    pub role: String,            // core | test | doc | config | new | modified | deleted
    pub diff_hash: String,       // SHA-256 of diff hunk
}

pub struct WormSeal {
    pub algorithm: String,       // "Ed25519"
    pub signature: String,       // 128 hex chars
    pub signer: String,          // "Plasma_Gate"
    pub audit_ref: String,       // UUID
}

src/schema.rs (70 lines)

pub const SCHEMA_VERSION: &str = "memory_bucket_v1";
pub const SCHEMA_URL: &str = "https://snapkitty.os/schema/memory-bucket-v1.json";
pub const VALID_TYPES: &[&str] = &[...];  // 6 types
pub const VALID_TRUST: &[&str] = &["verified", "pending", "disputed"];
pub const VALID_ROLES: &[&str] = &["core", "new", "modified", "deleted", "config", "test", "doc"];

pub fn validate_bucket(bucket: &MemoryBucket) -> Result<(), Vec<String>>;

Validates: id format (mem_NNNNNN), git hash (40 hex chars), type membership, trust membership, worm seal algorithm, immutability flag.

src/index.rs (111 lines)

pub struct Index {
    pub by_id: HashMap<String, MemoryBucket>,
    pub by_file: HashMap<String, Vec<String>>,      // path → [bucket IDs]
    pub by_entity: HashMap<String, Vec<String>>,     // entity → [bucket IDs]
    pub by_topic: HashMap<String, Vec<String>>,      // keyword → [bucket IDs]
    pub by_type: HashMap<String, Vec<String>>,       // type → [bucket IDs]
    pub by_agent: HashMap<String, Vec<String>>,      // author id → [bucket IDs]
}

impl Index {
    pub fn from_dir(buckets_dir: &str) -> Result<Self>;
    pub fn insert(&mut self, bucket: MemoryBucket);
    pub fn query(&self, field: &str, value: &str) -> Vec<&MemoryBucket>;
}

Query dispatches on field: topic/keyword → by_topic, file → by_file, entity → by_entity, type → by_type, agent → by_agent.

src/planner.rs (106 lines)

pub struct ContextBundle {
    pub context: Context,         // {buckets: ContextPiece[], total_tokens: usize}
    pub audit: AuditTrail,        // {query, buckets, verifier, timestamp, count}
}

pub fn query(field: &str, value: &str, budget: usize) -> Result<ContextBundle>;

Builds a proof-carrying context bundle: resolves query against index, constructs ContextPiece[] within token budget (estimated as summary.len() + files.len() * 50), and attaches audit trail with timestamp and query spec.

src/seal.rs (75 lines)

pub fn keygen() -> Result<(String, String)>;                    // (pubkey, privkey)
pub fn sign_bucket(bucket: &MemoryBucket, key: &SigningKey) -> String;
pub fn verify_bucket(bucket: &MemoryBucket, key: &VerifyingKey) -> Result<bool>;
pub fn verify_all(buckets_dir: &str) -> Result<Vec<Result<()>>>;

Signing payload: format!("{}:{}:{}", bucket.id, bucket.git_hash, bucket.timestamp), double-wrapped: SHA-256 → Ed25519 sign → hex encode.

src/extractor.rs (271 lines)

pub fn extract_range(repo: &str, from: Option<&str>, to: Option<&str>) -> Result<Vec<MemoryBucket>>;
fn parse_conventional_commit(message: &str) -> ParsedCommit;
fn classify_file_role(path: &str) -> String;
fn extract_entities_from_files(files: &[FileEntry]) -> Vec<String>;

src/main.rs (121 lines)

CLI entry point with clap derive parser. Dispatches to extractor/sealer/index/planner based on subcommand.

Prolog Runtime

config.pl (42 lines)

Module: config. Exports 4 predicates:

schema_version(memory_bucket_v1).          % Schema version
worm_algorithm(ed25519).                   % WORM signing algorithm
extractor_version(Extractor, Version).     % 4 extractors, each 1.0.0
trust_policy(Policy).                      % trusted_keys/1, branch_trust/1, breaking_change_trust/1

Trust policy defines 2 trusted keys (SnapKitty, Plasma_Gate), branch trust map (main:verified, develop:pending, _:pending), and breaking change trust (pending).

index.pl (142 lines)

Module: index. 7 dynamic predicates:

:- dynamic memory_bucket/1.
:- dynamic idx_file/2.       % idx_file(+Path, -BucketID)
:- dynamic idx_entity/2.     % idx_entity(+Entity, -BucketID)
:- dynamic idx_topic/2.      % idx_topic(+Topic, -BucketID)
:- dynamic idx_agent/2.      % idx_agent(+AgentID, -BucketID)
:- dynamic idx_time/2.       % idx_time(+Timestamp, -BucketID)
:- dynamic idx_dep/2.        % idx_dep(+ParentID, -ChildID)
:- dynamic idx_type/2.       % idx_type(+Type, -BucketID)

Facts are asserted dynamically from JSON files via load_buckets/1. Each bucket triggers index_bucket/1 which populates all 7 indices.

query.pl (151 lines)

Module: query. Main entry point:

assemble_context(+QuerySpec, -ContextBundle)  % Main query predicate
query_buckets(+QuerySpec, -BucketIDs, -Buckets)  % Raw query (no budget)
topological_sort(+Buckets, -Sorted)  % Kahn's algorithm on dependency graph
build_context(+OrderedBuckets, +Budget, -Context)  % Token-budgeted context

Query resolution supports 6 query types: topic, file, entity, agent, type, since/until (time range). The fit_budget/3 predicate implements a greedy token budget algorithm: estimate_tokens(Piece, Tokens) :- string_length(Summary, SLen), length(Files, FLen), Tokens is SLen + (FLen * 50).

plasma_gate.pl (87 lines)

Module: plasma_gate. Ed25519 cryptographic interface:

sign(+Data, +PrivKey, -Signature)          % SHA-256 → Ed25519 sign (stub)
verify(+Data, +Signature, +PubKey)          % Verify Ed25519 signature (stub)
keygen(-PubKey, -PrivKey)                   % Generate keypair (stub)
seal_bucket(+Bucket, -SealedBucket)         % Seal bucket with WORM seal
verify_bucket(+Bucket)                      % Verify bucket's WORM seal

In production, these stubs would be replaced with WASM-compiled Ed25519 native code.

Multi-Dimensional Index

Rust Index (src/index.rs)

In-memory HashMap-backed index built at query time from .gitbucket/buckets/*.json.

Index {
  by_id:     HashMap<id, MemoryBucket>           — primary storage
  by_file:   HashMap<file_path, Vec<id>>          — "what commits touched this file?"
  by_entity: HashMap<entity_name, Vec<id>>        — "where is this entity referenced?"
  by_topic:  HashMap<keyword, Vec<id>>            — "what topics are discussed?"
  by_type:   HashMap<bucket_type, Vec<id>>        — "all architecture decisions"
  by_agent:  HashMap<author_id, Vec<id>>          — "what did this agent do?"
}

Prolog Index (index.pl)

Dynamic predicate fact base loaded from JSON files. 7 indices with 7 distinct query predicates:

query_by_file(Path, Buckets)          % Files changed → buckets
query_by_entity(Entity, Buckets)      % Named entity → buckets
query_by_topic(Topic, Buckets)        % Keyword topic → buckets
query_by_agent(AgentID, Buckets)      % Author → buckets
query_by_time(From, To, Buckets)      % Time range → buckets
query_by_dep(ParentID, Children)      % Dependency → child buckets
query_by_type(Type, Buckets)          % Bucket type → buckets

Query Examples

% All buckets about authentication
?- index:query_by_topic("authentication", Buckets).

% Who changed the seal module?
?- index:query_by_file("src/seal.rs", Buckets).

% All decisions made in Q2 2026
?- index:query_by_time("2026-04-01", "2026-07-01", Buckets).

% Full context bundle with proof-carrying audit
?- query:assemble_context(_{topic: "scheduler", budget: 4000}, Bundle).

% Children of a specific bucket
?- index:query_by_dep("mem_000042", Children).

% What type was bucket mem_000001?
?- memory_bucket(B), B.id = "mem_000001", B.type = Type.

% All agents who made architecture decisions
?- index:query_by_type("architecture", Buckets),
   forall(member(B, Buckets), (B.author = Author, writeln(Author.id))).

Trust Model

Levels

Level Criteria Meaning
verified Trusted Ed25519 signer, main branch, no breaking changes Safe to use in autopilot mode
pending Untrusted branch OR BREAKING CHANGE: present Requires human review before trust
disputed Signature mismatch OR signer key revoked or unknown Do not use — possible tampering

Evaluation (trust_evaluator.pl)

Three factors combined with "most restrictive wins" logic:

trust_combine([KeyTrust, BranchTrust, BreakingTrust], Result) :-
    (   member(disputed, Levels) -> Result = disputed
    ;   member(pending, Levels)  -> Result = pending
    ;   Result = verified
    ).

Trust Policy (config.pl)

trust_policy(trusted_keys([
    'ed25519:SnapKitty',
    'ed25519:Plasma_Gate'
])).

trust_policy(branch_trust([
    main: verified,
    develop: pending,
    _: pending
])).

trust_policy(breaking_change_trust(pending)).

WORM Sealing & Ed25519

Seal Generation

Payload = format("{}:{}:{}", id, git_hash, timestamp)
PayloadHash = SHA-256(Payload)
Signature = Ed25519_Sign(PrivKey, PayloadHash)
WormSeal = {
    algorithm: "Ed25519",
    signature: hex(Signature),     # 128 hex chars
    signer: "Plasma_Gate",
    audit_ref: UUID v4
}

Seal Verification

Payload = format("{}:{}:{}", id, git_hash, timestamp)
PayloadHash = SHA-256(Payload)
ExpectedPubKey = lookup(signer)    # from trusted_keys
Result = Ed25519_Verify(ExpectedPubKey, PayloadHash, signature)

Key Generation

gitbucket keygen
# Public key:  ed25519:a8d72e4f1b3c5e7d9f0a2b4c6d8e0f1a3b5c7d9e
# Private key: ed25519:19fd33a1b2c4d6e8f0a2b4c6d8e0f1a3b5c7d9e

Batch Verification

gitbucket verify
#   23 passed, 0 failed

Skill Registry

skills/registry.json

Two registered skills at schema memory_bucket_v1:

Skill Version Provides Requires Memory
ledger_validation_v3 3.0.0 validateLedgerEntry sha256, stableStringify mem_genesis_ledger
borrow_chain_scheduler_v1 1.0.0 scheduleBorrows topoSort mem_genesis_borrow

Both skills have trust: "verified" authored by SnapKitty.

Skill Artifacts

ledger_validation_v3/

File Lines Purpose
impl.mjs 13 Validates debit == credit for ledger entries
verify.mjs 6 P-time verifier for ledger validation output
manifest.json 7 Declares provides/requires/version
proof_example.json — Sample (input, output, proof) for testing

Implementation (impl.mjs): Takes {entry: {debit, credit}}, returns {valid: boolean, proof: {balanced, debit, credit}}.

Verifier (verify.mjs): P-time check that output.valid === (debit === credit) and proof.balanced === (debit === credit).

borrow_chain_scheduler_v1/

File Lines Purpose
impl.mjs 30 Kahn topological sort for borrow chain dependency resolution
verify.mjs 12 P-time verifier for topological sort correctness
manifest.json 7 Declares provides/requires/version
proof_example.json — Sample (input, output, proof) for testing

Implementation (impl.mjs): Standard Kahn's algorithm — computes incoming degree map, processes nodes with zero incoming edges in sorted order.

Verifier (verify.mjs): Checks that schedule contains all nodes, all edges respect topological order (from appears before to in schedule), and no nodes are missing.

Skills Scripts

Fifteen scripts in skills/scripts/:

Python Scripts (11)

Script Lines Description
axiom_kernel.py 197 AXIOM proof assistant kernel. Implements ProofTerm, AXIOMKernel with phi_squared and phi_inverse theorem verification. Integrates with WORM chain for proof sealing.
constitutional_boot.py 249 6-stage cold boot sequence: SHREW → ILLUMINATE → RAT → ALIGNMENT → CATCODE → SOVEREIGN. Implements WORMChain SHA-256 ledger, BootSequence state machine, and 12 ArchitectsOfThought constitutional principles. CATCODE detection regex patterns.
alignment_checker.py 199 Constitutional alignment scoring. 12 Architects of Thought principles as code, AlignmentChecker with 5-category evaluation (freedom, truth, sovereignty, transparency, correctness), CATCODE heuristic detection.
collatz_10k.py 145 Collatz conjecture verifier for n ∈ [1, 10000]. CollatzVerifier class with step counter, max value tracker, WORM chain sealing.
ramsey_r33.py 173 Ramsey theorem R(3,3) = 6 proof via exhaustive 2-coloring enumeration (2^(C(6,2)) = 32768 colorings). RamseyVerifier with monochromatic triangle detection (K_3).
hadamard_h12.py 183 Hadamard H_12 matrix construction via Paley construction (order 12). HadamardConstructor with H * H^T = 12 * I verification, row orthogonality, WORM seal output.
mathrosetta_axiom.py 222 LaTeX → AXIOM proof syntax translator. Domain mapping (N→Nat, Z→Int, ...), AXIOMTranslator with quantifier support, theorem/lemma/proof skeleton generation.
literature_importer.py 201 Batch import theorems from LaTeX literature files. Converts LaTeX theorem environments to AXIOM proofs via MathRosetta translator.
multi_witness.py 283 3-witness consensus system requiring agreement from APL array computations, Lean 4 formal proofs, and AXIOM proof terms. Implements APLWitness, LeanWitness, AXIOMWitness with majority vote.
nats_bridge.py 210 NATS JetStream bridge for inter-agent proof communication. At-least-once delivery, replay, WORM sealing. Async Python with asyncio.
orchestrator_stage4.rb 86 Stage 4 AXIOM integration (Ruby). Calls Python axiom_kernel.py, verifies theorems (phi_squared, phi_inverse), seals results in WORM chain.

Node.js Scripts (1)

Script Lines Description
omega-field.mjs 186 SnapKitty Ω Field Reader. Queries GitHub API across 4 SnapKitty accounts/users (SNAPKITTYWEST, AHMADALIPARR, SNAPKITTYAGENT9NOVA, SNAPKITTY-COLLECTIVE-LIMITED-FLP). Computes entropy(E), evaluates coherent(system), maps intercoil dependency graph, emits SHA-256 WORM seal.

Shell Scripts (3)

Script Lines Description
build-all.sh 3 nix build .#all --impure — Nix-based monorepo build
verify-worm.sh 3 WORM chain verification stub
generate-sbom.sh 3 SBOM (Software Bill of Materials) generation stub

QWEN Skill Packets

Nineteen QWEN AI skill documentation files in skills/docs/qwen/:

Packet Filename Description
1 QWEN_AXIOM_ATTACK_STRATEGY.md AXIOM attack strategy — proving phi relations in type theory
2 QWEN_SKILLS_PACKET_2_SOVEREIGN_CALCULUS.md Sovereign calculus — Galois fields over Q(√5)
3 QWEN_SKILLS_PACKET_3_QUANTUM_GOLDILOCKS.md Quantum Goldilocks — three-point locking in Hilbert spaces
4 QWEN_SKILLS_PACKET_4_PRISM_TOPOLOGY.md PRISM topology — Postnikov tower decomposition
5 QWEN_SKILLS_PACKET_5_APL_MATHEMATICS.md APL mathematics — array-based sacred geometry
6 QWEN_SKILLS_PACKET_6_MATHROSETTA.md MathRosetta — cross-system proof translation
7 QWEN_SKILLS_PACKET_7_EXO_SYNCHRONICITY.md Exo-synchronicity — cross-agent coordination patterns
8 QWEN_SKILLS_PACKET_8_FIBONACCI.md Fibonacci — phi-based resonance chain
9 QWEN_SKILLS_PACKET_9_ORCHESTRATION.md Orchestration — sovereign stack integration
10 QWEN_SKILLS_PACKET_10_CONSTITUTION.md Constitution — architectures of thought
11 QWEN_SKILLS_PACKET_11_NATS.md NATS — inter-agent messaging protocol
12 QWEN_SKILL_AUDIT.md Full skill audit — registry review
13 QWEN_MATHEMATICAL_SKILLS.md Mathematical skills inventory
14 QWEN_PHASE_1_AXIOM_INTEGRATION.md Phase 1 AXIOM integration plan
15 QWEN_NEXT_MISSION.md Next mission brief
16 QWEN_NEXT_MISSION_PARALLEL.md Parallel mission tracks
17 QWEN_FIX_GITHUB_PAGES_404.md GitHub Pages 404 fix guide
18 QWEN_CLEANUP_GITHUB_PAGES.md GitHub Pages cleanup
19 QWEN_EXTRACT_APL_SKILLS.md Extract APL skills into standalone modules

Plans

Seven strategic plans in skills/docs/plans/:

Plan File Description
Infrastructure Audit COMPLETE_INFRASTRUCTURE_AUDIT.md Full audit of all repos, CI/CD, secrets, and deployment
Master Orchestration MASTER_INTEGRATION_ORCHESTRATION.md Cross-repo integration orchestration
MathRosetta MATHROSETTA_INTEGRATION_PLAN.md MathRosetta proof translator deployment
Multi-Witness MULTI_WITNESS_VERIFICATION.md 3-witness consensus pipeline (APL + Lean4 + AXIOM)
P vs NP Attack P_VS_NP_ATTACK_PLAN.md Strategy for P vs NP in the swarm context
Sovereign Orchestrator SOVEREIGN_ORCHESTRATOR_INTEGRATION.md Ruby orchestrator full integration
Unified Infrastructure UNIFIED_INFRASTRUCTURE_GUIDE.md Single-pane infrastructure view

Surveys

Three surveys in skills/docs/surveys/:

Survey File Description
ALL APL ALL_APL_SURVEY.md Comprehensive survey of APL mathematics used across the sovereign stack
Exosynchronicity EXOSYNCHRONICITY_SURVEY.md Survey of exo-synchronicity patterns in multi-agent systems
MathRosetta MATHROSETTA_SURVEY.md Survey of theorem translation capabilities between proof systems

External Crates

sovereign-prism (Rust library crate)

External library at external/. Cargo package sovereign-prism v0.1.0.

Dependencies: serde, serde_json, sha2, hex.

Modules (7 source files):

Module Lines Description
src/lib.rs 27 Module exports. Re-exports: ProofOfWork, Block, WormSeal, canonical_bytes, hash_bytes, hash_string, hash_double, snapsha256d, Carrier, pipeline, AdmissionValidator, PrimeIndexValidator.
src/sha256d.rs 75 Double SHA-256 hashing. hash_bytes(), hash_string(), hash_double(), snapsha256d(). Prevents length-extension attacks. Test vectors for empty input.
src/seal.rs 106 WORM Seal: Write-Once-Read-Many cryptographic witnesses. WormSeal struct with label, payload, steps, timestamp, seal_hash, artifact. Format: WORM:<label>:<payload>:<steps>:<timestamp>. verify() method recomputes hash. content_hash() isolates label+payload hash from timestamp.
src/psi_pipeline.rs 137 ψ-Pipeline: Algebraic topology stages. Carrier is typed I/O boundary. 4 stages: Nerve (simplicial set 1-skeleton) → Postnikov Tower (k-invariant filtration) → Homotopy Groups (π_0, π_1, π_k) → k-Invariants (SHA-256d hash). psi_pipeline() composes all 4 stages. Pipe trait for .pipe() chaining.
src/pow.rs 31 Proof of Work. ProofOfWork struct with difficulty parameter. mine(): iterative nonce search for leading-zero hash. verify(): check nonce produces expected hash prefix.
src/canonical.rs 83 Canonical JSON serialization via BTreeMap key sorting. canonical_bytes() produces deterministic byte representation. Recursive canonicalize_value() handles null, bool, number, string, array, object. Key insight: lexicographic key ordering ensures same logical JSON → same bytes.
src/block.rs 20 Block struct: height, hash, prev_hash, data, nonce. genesis(): SHA-256("GENESIS") → self-referential genesis block.
src/admission.rs 174 Admission validation with fail-closed semantics. AdmissionValidator: allowed-targets whitelist validation. PrimeIndexValidator: prime index membership check. AdmissionError enum: TargetNotInAllowedSet, InvalidTargetFormat, EmptyAllowedSet. Fail-closed: any error = rejected, no default/fallback.

sovereign-ruby (Ruby library)

Two Ruby modules in external/sovereign-ruby/lib/:

orchestrator.rb (146 lines)

Top-of-stack orchestrator: Ruby → Clojure/SICMUtils → APL → WORM.

  • WORM module: In-memory SHA-256 chained seal ledger with valid? chain verification
  • Stage 1 (Clojure): Calls clojure -M -m sovereign.core for symbolic TRS computation over Q(√5). Falls back to inline computation with 4 bias vectors (ME, AN, KI, DINGIR) across 8 depth levels, φ-resonance weighting, Galois conjugation (σ: φ → -1/φ).
  • Stage 2 (APL): Inline sacred geometry computation (same bias vectors, φ-weighted TRS).
  • Stage 3 (Seal): Combines Clojure + APL results into final WORM seal. Computes Δ (|TRS_Clj - TRS_APL|), attaches chain validity flag.
  • Constants: PHI = (1 + √5) / 2, PHI_INV = 1 / PHI.

axiom_stage.rb (63 lines)

Stage 3.5: AXIOM formal proof verification between APL (stage 2) and WORM seal (stage 4).

  • Calls axiom verify <proof_file> if AXIOM is in PATH.
  • Scans proof source for sorry count.
  • Provides integration hooks for orchestrator.rb (commented code showing where to insert).

Testing

tests/seal_tests.rs (94 lines)

Test Assertion
test_keygen Keys start with ed25519:, are different
test_sign_bucket Signature is 128 hex chars (64 bytes)
test_verify_bucket Valid signature verifies to true
test_verify_rejects_tampered Tampered signature verifies to false

tests/schema_tests.rs (76 lines)

Test Assertion
test_valid_bucket_passes Valid bucket → Ok(())
test_invalid_id_format bad_id → validation error
test_invalid_type "invalid" type → validation error
test_invalid_trust "unknown" trust → validation error
test_not_immutable immutable: false → validation error
test_schema_constants Constants match expected values

tests/extractor_tests.rs (35 lines)

Test Assertion
test_parse_feat_commit feat(auth): message contains expected tokens
test_parse_fix_commit fix(scheduler): message contains expected tokens
test_parse_breaking_change BREAKING CHANGE: detected in message
test_file_role_classification Path→role mapping expectation (assertion stubs)

Running Tests

cargo test                    # all tests
cargo test seal::             # seal tests only
cargo test schema::           # schema tests only
cargo test extractor::        # extractor tests only

Five Invariants

┌─────────────────────────────────────────────────────────────────┐
│                    FIVE INVARIANTS                                │
├─────────────────────────────────────────────────────────────────┤
│  1. DETERMINISM                                                  │
│     Same commit + same extractor version → bit-identical JSON    │
│     No randomness. No floating point. No system calls.           │
│                                                                  │
│  2. IMMUTABILITY                                                 │
│     Once sealed, buckets cannot be modified.                     │
│     `immutable: true` is enforced by schema validation.          │
│                                                                  │
│  3. TAMPER-EVIDENCE                                              │
│     SHA-256 chain links every bucket to its predecessor.         │
│     Ed25519 seals detect any modification.                       │
│                                                                  │
│  4. NON-REPUDIATION                                              │
│     Ed25519 signatures prove authorship.                         │
│     Signer identity is embedded in every worm_seal.              │
│                                                                  │
│  5. AUDITABILITY                                                 │
│     Every query produces an AuditTrail.                          │
│     Every seal has an audit_ref (UUID).                          │
│     Every read/write leaves a Decision Seal.                     │
└─────────────────────────────────────────────────────────────────┘

Integration Guide

As a Rust Library

# Cargo.toml
[dependencies]
snapkitty-gitbucket = { git = "https://github.com/SNAPKITTYWEST/snapkitty-gitbucket" }
use snapkitty_gitbucket::bucket::MemoryBucket;
use snapkitty_gitbucket::extractor::extract_range;
use snapkitty_gitbucket::index::Index;
use snapkitty_gitbucket::planner::query;
use snapkitty_gitbucket::schema::validate_bucket;
use snapkitty_gitbucket::seal::{keygen, sign_bucket, verify_bucket};

// Extract buckets from a repo
let buckets = extract_range("/path/to/repo", None, Some("HEAD"))?;

// Validate each bucket
for bucket in &buckets {
    validate_bucket(bucket)?;
}

// Build index and query
let index = Index::from_dir(".gitbucket/buckets")?;
let results = index.query("topic", "authentication");

// Query via planner (with audit trail and token budget)
let bundle = query("agent", "SnapKitty", 8000)?;

Bifrost WORM Chain Integration

Every bucket seal can anchor to a Bifrost WORM block:

sequenceDiagram
    participant Git as Git Commit
    participant GB as GitBucket
    participant BF as Bifrost Chain

    Git->>GB: commit (hash, author, message)
    GB->>GB: extract → MemoryBucket
    GB->>GB: sign → WORM seal
    GB->>BF: anchor(seal_hash, audit_ref)
    BF->>BF: append to WORM block
    BF-->>GB: block_hash
    GB->>GB: store block_hash in bucket
Loading

Sovereign OS Integration

Fiscal decisions are automatically classified when commit message uses fiscal: prefix:

git commit -m "fiscal(budget): allocate 1000 tokens to Q3 operations"

This produces a bucket with type: fiscal_decision, enabling treasury tracking through the index.

CI/CD Pipeline

name: GitBucket Verify
on: [push]
jobs:
  extract-and-verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: cargo build --release
      - run: ./target/release/gitbucket extract --repo .
      - run: ./target/release/gitbucket verify
      - run: swipl -g "index:load_buckets('.gitbucket/buckets')" -t halt

Agent Directives

For AI Agents Operating in This Repo

  1. Read First: The P/NP Swarm protocol means solutions are NP-hard to find but P-time to verify. Read AGENTS.md and the skill registry before claiming problems.

  2. Memory Protocol: Every commit creates a new bucket. Use assemble_context(Topic, Bundle) to query historical memory. The bundle includes a proof-carrying audit trail — verify before trusting.

  3. Skills as Memories: Skills are not code files. They are sealed GitBucket memories with verifyFn (WASM). Use skillLoader.load() to load a skill, then call verify(execute(input)) before trusting the output.

  4. Claim → Solve → Submit → Verify → Converge:

    • Read problem_registry.json for open problems
    • Append claim to claim_ledger.jsonl
    • Compute witness (NP-hard work)
    • Write solution to solution_pool/
    • CI runs pnpVerifier.js — P-time verification
    • On success: problem → solved, universe sum advances

  5. Determinism is Law: Same extractor version + same input = bit-identical output. Never attempt to inject randomness into the extraction pipeline.

  6. Trust Cascade: Trust is computed from three factors (signer, branch, breaking changes). The most restrictive factor wins. Never use a disputed bucket in automated decision-making.

  7. Convergence Metric: Track universeSum — every solved problem increases it. The goal is monotonic convergence toward the fixed point of the problem space.

For Human Operators

  • Use gitbucket extract after significant commits to keep the index current
  • Run gitbucket verify before deploying — if seals fail, investigate tampering
  • Use fiscal: commit prefix for treasury decisions — they auto-tag as fiscal_decision
  • The Prolog runtime enables ad-hoc queries beyond the CLI index — use swipl directly for complex queries
  • All 5 invariants are enforced by schema validation — bypassing them breaks trust guarantees

License

MIT OR Apache-2.0

Copyright 2026 SnapKitty Collective

╔══════════════════════════════════════════════════════════════════╗
║              SNAPKITTY GITBUCKET — DETERMINISTIC MEMORY          ║
║              Git as WORM · JSON as Query · Prolog as Truth       ║
║              Ed25519 · SHA-256 · 5 Invariants · P/NP Swarm       ║
╚══════════════════════════════════════════════════════════════════╝

About

[ARCHIVED] Deterministic Memory Layer — Git as WORM, JSON as Query, Prolog as Truth — SSL v3.0

Resources

Readme
Activity

Stars

3 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages