laantungir/ngit-grasp

Fork 0

mirror of https://relay.ngit.dev/npub15qydau2hjma6ngxkl2cyar74wzyjshvl65za5k5rl69264ar2exs5cyejr/ngit-grasp.git synced 2026-10-05 15:08:24 +00:00

Files

T

History

DanConwayDev 6e9bf5981b fix(lifecycle): preserve NIP-01 ordering through deletion and rollback

Same-second lower-ID replacements could be ignored by served-repository
de-listing and superseded-history capture. Rollback's active-state lookup
and post-deletion alignment instead preferred higher IDs, while history
selection let capture time override the original event's replacement order.

Share the later-timestamp/lower-ID comparator across these lifecycle paths
and the existing purgatory decisions. Archive a same-second predecessor only
when the incoming event wins, and only apply de-list deletion for a winning
replacement. Select active and authorized alignment states with the same
ordering. Rank history records by original timestamp and original event ID
before capture metadata; keep timestamp cutoffs and author checks intact.

Extract the authorized-state selection used by realignment to exercise both
arrival orders with different authorized authors and an unauthorized newer
state. Add served de-list, history-capture and history-candidate regressions.
All four new regressions fail before the fixes and pass afterward. Extend the
LMDB restart scenario to delete the same-second winner and observe its
archived predecessor restored, with a bounded deadline and no new sleeps.

This changes replacement preference, not deletion request ownership,
coordinate cutoff semantics, repository membership or archive format.
Existing capture metadata remains readable. Update the changelog and
repository lifecycle documentation.

Validation: focused ordering regressions and LMDB restart/rollback test;
full ngit-grasp suite, all-target workspace Clippy with warnings denied,
formatting and diff checks pass.

Assisted-by: GPT-6

2026-09-17 15:38:24 +00:00

archive/2026-01-relay-ngit-dev-migration

fix migration scripts for non-interactive SSH and bash 5.3

2026-02-24 08:58:23 +00:00

explanation

fix(lifecycle): preserve NIP-01 ordering through deletion and rollback

2026-09-17 15:38:24 +00:00

grafana

feat(sync): Phase 6 - observability and production readiness

2025-12-04 18:43:49 +00:00

how-to

test: order replacement fixtures by explicit predecessors

2026-09-17 15:12:02 +00:00

learnings

refactor(auth): make current maintainer authority explicit

2026-08-29 21:20:49 +00:00

reference

refactor(relay): retire overrides supplied by the upgraded SDK

2026-09-17 13:44:47 +00:00

tutorials

docs: use Diátaxis structure

2025-11-04 10:25:53 +00:00

README.md

docs(deploy): add host-specific production paths

2026-08-20 19:38:04 +00:00

README.md

ngit-grasp Documentation

Welcome to the ngit-grasp documentation! We use the Diátaxis framework to organize our documentation into four types, each serving a different purpose.

                    PRACTICAL          THEORETICAL
                    ─────────          ───────────
                    
LEARNING      │   Tutorials    │    Explanation   │
              │                │                  │
              │  Getting       │   Architecture   │
              │  Started       │   Decisions      │
              │                │                  │
              ├────────────────┼──────────────────┤
              │                │                  │
WORKING       │  How-To        │    Reference     │
              │  Guides        │                  │
              │                │   API Docs       │
              │  Deployment    │   Protocols      │
              │  Testing       │                  │
              │                │                  │

📚 Documentation Types

🎓 Tutorials - Learning by Doing

Purpose: Learn the basics through practical steps
For: Newcomers getting started
Style: Step-by-step lessons with guaranteed outcomes

Getting Started - Your first ngit-grasp setup
Running Your First Audit - Using grasp-audit tool

🔧 How-To Guides - Solving Problems

Purpose: Accomplish specific tasks
For: Users with basic knowledge solving real problems
Style: Practical recipes and solutions

Deploy ngit-grasp - Choose Docker, NixOS, Linux, Proxmox, or managed hosting
Deployment contract - Shared runtime and persistence requirements
Configure Nix Flakes - Nix development environment
Run Compliance Tests - GRASP compliance testing
Upgrade nostr-sdk - Handling SDK upgrades

📖 Reference - Technical Information

Purpose: Look up technical details
For: Users who know what they're looking for
Style: Dry, factual, comprehensive

Git Protocol - Git Smart HTTP protocol details
GRASP Protocol - GRASP specification details
Configuration - All config options
API Reference - Internal API documentation

💡 Explanation - Understanding Concepts

Purpose: Understand the "why" and design decisions
For: Users wanting deeper understanding
Style: Discussion, context, alternatives

Architecture Overview - System design and components
Inline Authorization - Why we chose this approach
Administration Vision - Nostr-authenticated management, embedded UI, and runtime configuration
Comparison with ngit-relay - How we differ from reference
Design Decisions - Key architectural choices

🚀 Quick Start Paths

I'm brand new to ngit-grasp

Read README.md for project overview
Follow Getting Started Tutorial
Understand Architecture Overview

I want to deploy ngit-grasp

Review Configuration Reference
Choose an environment in Deploy ngit-grasp
Verify the deployment and test its backup

I want to develop on ngit-grasp

I want to understand the design

I'm looking for specific information

Protocol details? → Reference
Configuration options? → Configuration Reference
Git protocol? → Git Protocol Reference

📂 Additional Resources

Learnings

DEPRECATED - Being migrated to Diátaxis structure:

Gotchas → How-To Guides
Patterns → Reference or Explanation
Notes → Appropriate category

🤝 Contributing to Documentation

When adding documentation, ask yourself:

Is it a tutorial?

Does it teach a beginner?
Is it a complete lesson with guaranteed outcome?
→ Add to tutorials/

Is it a how-to guide?

Does it solve a specific problem?
Is it a recipe for accomplishing a task?
→ Add to how-to/

Is it reference material?

Is it technical information?
Will people look it up when needed?
→ Add to reference/

Is it explanation?

Does it explain "why"?
Does it discuss alternatives or design?
→ Add to explanation/

See Diátaxis documentation for more guidance.

📊 Project Status

ALPHA - Under active development. Core functionality working, API may change.

Completed

✅ grasp-audit compliance testing tool
✅ Nix flake development environment
✅ nostr-sdk 0.43 upgrade
✅ Documentation restructure (Diátaxis)

In Progress

🔄 Core ngit-grasp server implementation
🔄 GRASP-01 compliance

Planned

🔜 GRASP-02 (Proactive Sync)
🔜 GRASP-05 (Archive)

🔗 External Links

Documentation structure based on Diátaxis
Last updated: November 4, 2025