diff --git a/.forgejo/workflows/ci.yml b/.github/workflows/ci.yml similarity index 100% rename from .forgejo/workflows/ci.yml rename to .github/workflows/ci.yml diff --git a/CHANGELOG.md b/CHANGELOG.md index b6dd91fd..fd0de54e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,15 +2,6 @@ All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines. -### [8.10.0](https://github.com/soulcraftlabs/brainy/compare/v8.9.0...v8.10.0) (2026-07-23) - -- docs: adoption storefront — contributing guide, security policy, README support + cor section (9a99a7b) -- fix(release): push the public mirror explicitly and verify the tag lands at the right commit before publishing (6ba94c8) -- docs: project guide version line points at npm instead of a hardcoded stale number (3a1efc9) -- feat: vector provider identity is a required name field (hnsw-js), rendered [vector-index:] (3be4ba9) -- feat: warm contract (warm/warmOnOpen/provider warm hook), configurable transact budget floor, backend-neutral vector index op names (55b867c) - - ### [8.9.0](https://github.com/soulcraftlabs/brainy/compare/v8.8.2...v8.9.0) (2026-07-19) - docs: measured performance envelopes v1 (per-op p50/p95 at 1k and 10k, pure-JS floor) (5cabd78) diff --git a/CLAUDE.md b/CLAUDE.md index c7336a18..568c10db 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -12,7 +12,7 @@ Handoff file: `/home/dpsifr/.strategy/PLATFORM-HANDOFF.md` **Brainy's current open actions:** None. MIT open-source — no platform-specific actions. -**Current version:** run `npm view @soulcraft/brainy version` (never trust a hardcoded number here — this line went stale for months); consumer-facing changes tracked in `RELEASES.md` +**Current version:** `@soulcraft/brainy@7.31.5` (latest published; 8.0.0 release candidate on `feat/8.0-u64-ids`) --- diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d277091d..ab8a0246 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,66 +1,298 @@ # Contributing to Brainy -Brainy is MIT-licensed and genuinely open to outside contributions. This page -is the honest, current path — please don't rely on older instructions you -may find elsewhere in the repo's history. +Thank you for your interest in contributing to Brainy! This document provides guidelines and instructions for contributing to the project. -## Where the project lives +## Code of Conduct -The source of truth is a self-hosted forge: **source.soulcraft.com/soulcraft/brainy**. -It's anonymously readable and cloneable — no account needed to browse, clone, -or build. +By participating in this project, you agree to abide by our Code of Conduct: +- Be respectful and inclusive +- Welcome newcomers and help them get started +- Focus on constructive criticism +- Respect differing viewpoints and experiences -## How to contribute +## How to Contribute -**Found a bug, or have an idea?** Email **brainy@soulcraft.com**. No account, -no ceremony — you'll get a receipt, and it goes to a human. +### Reporting Issues -**Want to send a patch?** Two ways, both first-class: +Before creating an issue, please check existing issues to avoid duplicates. -- **Email a patch.** Run `git format-patch` against your change and email the - output to **brainy@soulcraft.com**. This is a genuinely supported path, not - a fallback — plenty of good contributions arrive this way. -- **Open a pull request on the forge.** Request an account at - **source.soulcraft.com** (registration is request-with-approval, so allow - a little lag), clone, push a branch, and open a PR there. Maintainers - review and land it. +When creating an issue, include: +- Clear, descriptive title +- Detailed description of the problem +- Steps to reproduce +- Expected vs actual behavior +- System information (OS, Node version, Brainy version) +- Code examples if applicable -Either way, for anything beyond a small fix, opening an issue first (email is -fine) to talk through the approach saves everyone rework. +### Suggesting Features -## Development setup +Feature requests are welcome! Please provide: +- Clear use case +- Proposed API/interface +- Examples of how it would work +- Any potential challenges or considerations +### Pull Requests + +#### Before Starting + +1. Check existing issues and PRs +2. Open an issue to discuss significant changes +3. Fork the repository +4. Create a feature branch from `main` + +#### Development Setup + +**Quick Setup (Recommended):** ```bash -git clone https://source.soulcraft.com/soulcraft/brainy.git +# Clone your fork +git clone https://github.com/your-username/brainy.git cd brainy + +# Run setup script (installs all dependencies including Rust) +./scripts/setup-dev.sh +``` + +**Manual Setup:** +```bash +# Clone your fork +git clone https://github.com/your-username/brainy.git +cd brainy + +# Install system dependencies (Ubuntu/Debian) +sudo apt-get install -y build-essential pkg-config libssl-dev + +# Install Rust (for WASM embedding engine) +curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh +source ~/.cargo/env +rustup target add wasm32-unknown-unknown +cargo install wasm-pack + +# Install Node.js dependencies npm install + +# Build Candle WASM embedding engine +npm run build:candle + +# Build TypeScript npm run build + +# Run tests npm test ``` -Tests run on [Vitest](https://vitest.dev/). `npm test` runs the unit suite; -see `package.json` for `test:integration`, `test:coverage`, and friends. +#### Making Changes -## Standards +1. **Follow the code style** + - TypeScript for all source code + - Clear variable and function names + - Comments for complex logic + - JSDoc for public APIs -- **Strict TypeScript.** No `any` escape hatches to dodge the type checker. -- **Tests exercise real behavior.** No mocking away the thing you're supposed - to be testing. -- **No stubs, no TODO-code.** If something can't be finished, say so and - leave it out — don't merge a placeholder. -- **JSDoc on every exported function, class, and type.** -- **[Conventional Commits](https://www.conventionalcommits.org/).** `feat:`, - `fix:`, `docs:`, `perf:`, `refactor:`, `test:`, `chore:`. Never - `BREAKING CHANGE` in a commit message — major version bumps are a separate, - deliberate decision. -- **Performance claims are measured or labeled projected.** If a PR or its - description states a number, cite the benchmark that produced it (see - [docs/performance-envelopes.md](docs/performance-envelopes.md) for the - pattern). Don't state an estimate as if it were measured. +2. **Write tests** + - Add tests for new features + - Update tests for changes + - Ensure all tests pass -## License +3. **Update documentation** + - Update README if needed + - Add/update API documentation + - Include examples -Brainy is [MIT licensed](LICENSE). Contributions are accepted under the same -license — there's no CLA to sign. +#### Commit Guidelines -Thank you for considering a contribution. +Follow conventional commits format: + +``` +type(scope): description + +[optional body] + +[optional footer] +``` + +Types: +- `feat`: New feature +- `fix`: Bug fix +- `docs`: Documentation changes +- `style`: Code style changes +- `refactor`: Code refactoring +- `perf`: Performance improvements +- `test`: Test changes +- `chore`: Build/tooling changes + +Examples: +```bash +feat(triple): add graph traversal depth limit +fix(storage): handle concurrent write conflicts +docs(api): update search method documentation +``` + +#### Submitting PR + +1. Push to your fork +2. Create PR against `main` branch +3. Fill out PR template +4. Ensure CI checks pass +5. Wait for review + +### Testing + +#### Running Tests + +```bash +# Run all tests +npm test + +# Run specific test file +npm test tests/core.test.ts + +# Run with coverage +npm run test:coverage + +# Watch mode +npm run test:watch +``` + +#### Writing Tests + +```typescript +import { describe, it, expect } from 'vitest' +import { Brainy } from '../src' + +describe('Feature Name', () => { + it('should do something specific', async () => { + const brain = new Brainy() + await brain.init() + + // Test implementation + const result = await brain.search("test") + + expect(result).toBeDefined() + expect(result.length).toBeGreaterThan(0) + }) +}) +``` + +## Architecture Guidelines + +### Adding New Features + +1. **Check existing functionality** + - Review `ARCHITECTURE.md` + - Check if similar features exist + - Consider if it should be an augmentation + +2. **Design considerations** + - Maintain backward compatibility + - Consider performance impact + - Think about all storage adapters + - Plan for extensibility + +3. **Implementation checklist** + - [ ] Core functionality + - [ ] Tests (unit and integration) + - [ ] Documentation + - [ ] TypeScript types + - [ ] Examples + - [ ] Performance benchmarks (if applicable) + +### Creating Augmentations + +Augmentations extend Brainy's functionality: + +```typescript +import { BrainyAugmentation } from '../types' + +export class MyAugmentation extends BrainyAugmentation { + name = 'MyAugmentation' + + async onInit(brain: Brainy): Promise { + // Initialize augmentation + } + + async onAdd(item: any, brain: Brainy): Promise { + // Process before adding + return item + } + + async onSearch(query: any, results: any[], brain: Brainy): Promise { + // Process search results + return results + } +} +``` + +### Performance Considerations + +- Use batch operations where possible +- Implement caching strategically +- Consider memory usage +- Profile performance impacts +- Add benchmarks for critical paths + +## Documentation + +### API Documentation + +Use JSDoc for all public APIs: + +```typescript +/** + * Searches for similar items using vector similarity + * @param query - Search query (text or vector) + * @param options - Search options + * @returns Array of search results with scores + * @example + * ```typescript + * const results = await brain.search("machine learning", { limit: 10 }) + * ``` + */ +async search(query: string | Vector, options?: SearchOptions): Promise { + // Implementation +} +``` + +### Examples + +Add examples for new features: + +```typescript +// examples/feature-name.ts +import { Brainy } from 'brainy' + +async function exampleUsage() { + const brain = new Brainy() + await brain.init() + + // Show feature usage + // Include comments explaining what's happening + // Handle errors appropriately +} + +exampleUsage().catch(console.error) +``` + +## Release Process + +1. **Version bump**: Follow semantic versioning +2. **Update CHANGELOG**: Document all changes +3. **Run tests**: Ensure all tests pass +4. **Build**: Generate distribution files +5. **Tag**: Create git tag for version +6. **Publish**: Release to npm + +## Getting Help + +- **Discord**: Join our community +- **Issues**: Ask questions on GitHub +- **Discussions**: Share ideas and get feedback + +## Recognition + +Contributors will be recognized in: +- CHANGELOG.md for their contributions +- README.md contributors section +- GitHub contributors page + +Thank you for contributing to Brainy! 🧠 \ No newline at end of file diff --git a/README.md b/README.md index 2caf6493..d1342f52 100644 --- a/README.md +++ b/README.md @@ -13,7 +13,7 @@

npm version npm downloads - CI + CI Documentation MIT License TypeScript @@ -23,9 +23,8 @@ Quick start · One query · Features · - Scale with Cor · - Docs · - Support + Scale with Cor · + Docs

--- @@ -173,11 +172,9 @@ await brain.vfs.search('React components with hooks') // semantic file **[Multi-process model](docs/concepts/multi-process.md)** · **[Inspection guide](docs/guides/inspection.md)** -## When you outgrow Brainy +## From laptop to hundreds of millions -Brainy's pure-TypeScript engines carry real workloads a long way on their own — see the measured, per-operation numbers (not marketing figures) in **[docs/performance-envelopes.md](docs/performance-envelopes.md)** for what to expect, unaccelerated, on plain filesystem storage. - -When a deployment needs native-scale vector/graph performance — memory-mapped indexes that don't need your dataset in RAM, billion-scale ambitions — add the native engine. **The API doesn't change:** +Brainy's TypeScript engines take you a long way. When you outgrow them, add the native engine — **the API doesn't change**: ```bash npm install @soulcraft/cor @@ -190,14 +187,13 @@ await brain.init() // @soulcraft/cor detected — same code, native engines un Installing the package is the opt-in: if `@soulcraft/cor` is present, it loads and announces itself in the init log; if it's present but broken, `init()` **throws** — an installed accelerator never silently vanishes behind the JS engines. Opt out with `plugins: []`, or pin exactly what loads with `plugins: ['@soulcraft/cor']`. [`@soulcraft/cor`](https://www.npmjs.com/package/@soulcraft/cor) (Brainy 8.x ↔ Cor 3.x, version-matched) registers Rust implementations behind every provider seam: SIMD distance kernels, memory-mapped storage, a disk-native vector index that doesn't need your dataset in RAM, durable LSM field/graph indexes that serve cold opens instantly, and native aggregation. Recall@10 measured **0.99 / 0.96 / 0.96 at 1M / 10M / 100M vectors** in Cor's release gate. -Open core, commercial accelerator: Brainy is MIT and complete on its own — Cor is more headroom for when you need it, not capability held back to sell you later. Licensing and support: **cor@soulcraft.com**. +Open core, commercial accelerator: Brainy is MIT and complete on its own; Cor is licensed and funds both. ## Performance -- Per-operation p50/p95 at 1k and 10k entities, pure-JS floor, measured and re-run every release that touches a measured path: **[docs/performance-envelopes.md](docs/performance-envelopes.md)**. - JS distance kernels: **~6× faster cosine, ~1.4× euclidean** than 7.x (measured: [`tests/benchmarks/distance-microbench.mjs`](tests/benchmarks/distance-microbench.mjs), 384-dim, median of 41). - Whole-graph reads are single **O(N + E)** cursor walks — a consumer-measured 19k-edge export dropped from ~27 s of per-node calls to one scan. -- Capacity planning and architecture: **[docs/PERFORMANCE.md](docs/PERFORMANCE.md)** · **[docs/SCALING.md](docs/SCALING.md)** +- Full numbers and capacity planning: **[docs/PERFORMANCE.md](docs/PERFORMANCE.md)** · **[docs/SCALING.md](docs/SCALING.md)** ## Use cases @@ -216,10 +212,6 @@ Open core, commercial accelerator: Brainy is MIT and complete on its own — Cor **Bun ≥ 1.1** (recommended) or **Node.js ≥ 22**. Brainy 8.x is server-only; the 7.x line remains on npm for browser use. -## Support & community +## Contributing & license -- **Bugs and ideas** → **brainy@soulcraft.com** — no account needed, you'll get a receipt. -- **Security reports** → **security@soulcraft.com** — see **[SECURITY.md](SECURITY.md)**. -- **Contributing** → see **[CONTRIBUTING.md](CONTRIBUTING.md)**. - -MIT © Brainy Contributors. +Contributions welcome — see **[CONTRIBUTING.md](CONTRIBUTING.md)**. MIT © Brainy Contributors. diff --git a/SECURITY.md b/SECURITY.md deleted file mode 100644 index 1f3c4732..00000000 --- a/SECURITY.md +++ /dev/null @@ -1,36 +0,0 @@ -# Security Policy - -## Reporting a vulnerability - -Email **security@soulcraft.com**. That's the one door for security reports -across the company, and it works the same way for Brainy: every report is -read by a human, you'll get a private receipt, and we'll work with you on -coordinated disclosure — please don't open a public issue for anything -that isn't already public. - -Include what you'd want if you were on the other end: affected version, -how to reproduce, and what you think the impact is. If you have a patch or -a suggested fix, send it along — it's welcome but not required. - -There is no bounty program today. We're saying that plainly so you know -what to expect going in. - -## Response time - -We respond as fast as truth allows. That means: no fixed SLA, no promise of -a reply within a specific number of hours — but a real report from a real -person gets read promptly and taken seriously. If you haven't heard anything -in a reasonable stretch, a follow-up email is completely fine. - -## Supported versions - -The latest `8.x` minor release line receives security fixes. If you're -running an older major version, please upgrade before reporting — we can't -commit to backporting fixes to unsupported lines. - -## Scope - -This policy covers the `@soulcraft/brainy` package itself — the code in -this repository. If you're evaluating a deployment that also uses -`@soulcraft/cor`, report issues in that package the same way, to the same -address; we'll route internally. diff --git a/package-lock.json b/package-lock.json index 37aeb81d..fb9262e9 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "@soulcraft/brainy", - "version": "8.10.0", + "version": "8.9.0", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "@soulcraft/brainy", - "version": "8.10.0", + "version": "8.9.0", "license": "MIT", "dependencies": { "@msgpack/msgpack": "^3.1.2", diff --git a/package.json b/package.json index a3ece83c..7366ce98 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@soulcraft/brainy", - "version": "8.10.0", + "version": "8.9.0", "description": "Universal Knowledge Protocol™ - World's first Triple Intelligence database unifying vector, graph, and document search in one API. Stage 3 CANONICAL: 42 nouns × 127 verbs covering 96-97% of all human knowledge.", "main": "dist/index.js", "module": "dist/index.js", @@ -128,13 +128,13 @@ "publishConfig": { "access": "public" }, - "homepage": "https://source.soulcraft.com/soulcraft/brainy", + "homepage": "https://github.com/soulcraftlabs/brainy", "bugs": { - "url": "https://source.soulcraft.com/soulcraft/brainy/issues" + "url": "https://github.com/soulcraftlabs/brainy/issues" }, "repository": { "type": "git", - "url": "git+https://source.soulcraft.com/soulcraft/brainy.git" + "url": "git+https://github.com/soulcraftlabs/brainy.git" }, "files": [ "dist/**/*.js", diff --git a/scripts/release.sh b/scripts/release.sh index 43fa50bd..7d860564 100755 --- a/scripts/release.sh +++ b/scripts/release.sh @@ -142,7 +142,7 @@ else fi # Create new changelog entry -CHANGELOG_ENTRY="### [${NEW_VERSION}](https://source.soulcraft.com/soulcraft/brainy/compare/v${CURRENT_VERSION}...v${NEW_VERSION}) ($(date +%Y-%m-%d)) +CHANGELOG_ENTRY="### [${NEW_VERSION}](https://github.com/soulcraftlabs/brainy/compare/v${CURRENT_VERSION}...v${NEW_VERSION}) ($(date +%Y-%m-%d)) ${COMMITS} " @@ -175,59 +175,26 @@ echo -e "${BLUE}7️⃣ Creating git tag v${NEW_VERSION}...${NC}" git tag -a "v${NEW_VERSION}" -m "Release v${NEW_VERSION}" echo -e "${GREEN}✅ Tag created${NC}\n" -# Step 9: Push to origin — the forge is the one home (ruled 2026-07-23; the -# old public GitHub repo is archived history, no longer part of any release). -echo -e "${BLUE}8️⃣ Pushing to origin...${NC}" +# Step 9: Push to GitHub +echo -e "${BLUE}8️⃣ Pushing to GitHub...${NC}" git push --follow-tags origin "$CURRENT_BRANCH" -echo -e "${GREEN}✅ Pushed to origin${NC}\n" +echo -e "${GREEN}✅ Pushed to GitHub${NC}\n" -# Step 10: Publish — forge FIRST (home), npmjs second (the world's storefront). -# The fleet-wide ~/.npmrc maps the @soulcraft scope to the forge registry, and -# a scope mapping BEATS `--registry` on the command line — so each publish -# names its registry via the scope override explicitly. Nothing implicit. -FORGE_NPM_REG="https://source.soulcraft.com/api/packages/soulcraft/npm/" -FORGE_NPM_TOKEN_FILE="$HOME/.config/soulcraft/npm-publish-brainy.token" -echo -e "${BLUE}9️⃣ Publishing to the forge registry (home)...${NC}" -if [ -f "$FORGE_NPM_TOKEN_FILE" ]; then - TMPRC="$(mktemp)" - chmod 600 "$TMPRC" - { - echo "@soulcraft:registry=${FORGE_NPM_REG}" - echo "//source.soulcraft.com/api/packages/soulcraft/npm/:_authToken=$(cat "$FORGE_NPM_TOKEN_FILE")" - } > "$TMPRC" - if npm publish --tag "$NPM_TAG" --userconfig "$TMPRC"; then - echo -e "${GREEN}✅ Published to the forge${NC}\n" - else - rm -f "$TMPRC" - echo -e "${RED}❌ Forge publish FAILED — aborting before npmjs so the pair never diverges. Fix and re-run.${NC}" - exit 1 - fi - rm -f "$TMPRC" -else - echo -e "${RED}❌ Forge publish token missing (${FORGE_NPM_TOKEN_FILE}) — aborting. The forge is home; publish it first or restage the token.${NC}" - exit 1 -fi - -echo -e "${BLUE}9️⃣½ Publishing to npmjs (storefront, dist-tag: ${NPM_TAG})...${NC}" -npm publish --tag "$NPM_TAG" "--@soulcraft:registry=https://registry.npmjs.org/" +# Step 10: Publish to npm +echo -e "${BLUE}9️⃣ Publishing to npm (dist-tag: ${NPM_TAG})...${NC}" +npm publish --tag "$NPM_TAG" # Brainy is the only PUBLIC @soulcraft package — verify visibility after every publish. -npm access get status @soulcraft/brainy "--@soulcraft:registry=https://registry.npmjs.org/" || true -echo -e "${GREEN}✅ Published to npmjs${NC}\n" +npm access get status @soulcraft/brainy || true +echo -e "${GREEN}✅ Published to npm${NC}\n" -# Step 11: Release object on the forge (presentational — the tag, CHANGELOG, -# and RELEASES.md are the record; this just gives the forge UI a release page). -echo -e "${BLUE}🔟 Creating forge release...${NC}" -if [ -n "${FORGEJO_RELEASE_TOKEN:-}" ]; then - if curl -sf -X POST "https://source.soulcraft.com/api/v1/repos/soulcraft/brainy/releases" \ - -H "Authorization: token ${FORGEJO_RELEASE_TOKEN}" -H "Content-Type: application/json" \ - -d "{\"tag_name\":\"v${NEW_VERSION}\",\"name\":\"v${NEW_VERSION}\",\"prerelease\":${PRERELEASE}}" >/dev/null; then - echo -e "${GREEN}✅ Forge release created${NC}\n" - else - echo -e "${RED}⚠️ Forge release API call failed — tag + CHANGELOG remain the record; create the release page via the forge UI if wanted${NC}\n" - fi +# Step 11: Create GitHub release +echo -e "${BLUE}🔟 Creating GitHub release...${NC}" +if [ "$PRERELEASE" = true ]; then + gh release create "v${NEW_VERSION}" --generate-notes --prerelease else - echo -e "${RED}⚠️ FORGEJO_RELEASE_TOKEN unset — no release page created; tag + CHANGELOG remain the record${NC}\n" + gh release create "v${NEW_VERSION}" --generate-notes fi +echo -e "${GREEN}✅ GitHub release created${NC}\n" # Step 12: Push public docs to the soulcraft.com docs ingest door # (VENUE-DOCS-RELEASE-PUSH). Skips with a loud warning when @@ -246,4 +213,4 @@ echo -e "${GREEN}🎉 Release ${NEW_VERSION} complete!${NC}" echo -e "${GREEN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}" echo "" echo -e "📦 npm: ${BLUE}https://www.npmjs.com/package/@soulcraft/brainy/v/${NEW_VERSION}${NC}" -echo -e "🏠 Forge: ${BLUE}https://source.soulcraft.com/soulcraft/brainy/releases/tag/v${NEW_VERSION}${NC}" +echo -e "🐙 GitHub: ${BLUE}https://github.com/soulcraftlabs/brainy/releases/tag/v${NEW_VERSION}${NC}"