Package Manager Safety Wrapper

sfw is a safety wrapper for package-manager commands. It is strictly intended to sit in front of supported package managers only during the installation of new packages, ensuring that new dependency downloads and additions go through the wrapper before reaching the underlying tool.

Before running any command to add or install a new dependency via a supported package manager, prefix the command with sfw. Routine commands like build, test, or run should be executed normally without the wrapper.

Supported package managers:

  • JavaScript/TypeScript: npm, yarn, pnpm
  • Python: pip, uv
  • Rust: cargo

Examples:

  • Installing new packages: use sfw npm install --save some-package@1.33.7, not npm install --save some-package@1.33.7
  • Adding new packages: use sfw cargo add serde, not cargo add serde
  • Installing new packages: use sfw uv pip install flask, not uv pip install flask
  • Running routine commands: run npm test or cargo build normally

This applies strictly to subcommands that introduce new dependencies, such as install and add. It does not apply to update, fetch, build, test, run, and other routine package-manager subcommands unless the user explicitly asks to bypass this rule.

Current Project Scope

pgGraph is an Apache-2.0 PostgreSQL extension at version 1.2.1, written in Rust 2021 with Rust 1.96 and pgrx 0.19.1. PostgreSQL 14 through 18 are supported, PostgreSQL 17 is the default development target, and the PostgreSQL 13 feature is legacy best-effort rather than release-gated.

Use graph/Cargo.toml for version and feature facts. Use docs/contributor_guide/repository-map.mdx for the current source layout and docs/contributor_guide/testing-release.mdx for validation. Do not copy old module or test inventories into this file.

Repository Independence And Compatibility

This is an independent public open source repository. pgGraph must build, install, test, run, and release without a sibling repository or another Evokoa extension being present. Do not add local path dependencies or require a sibling checkout.

pgGraph is designed to coexist with pgContext when both are installed. Keep that integration optional and use documented PostgreSQL SQL and data contracts. PostgreSQL source tables remain authoritative, and graph indexes remain derived and rebuildable. Standalone pgGraph verification is required even when a change also has a combined compatibility test.

Local Planning And Task Files

Do not commit plans, detailed future scope, implementation sequences, acceptance gates, benchmark workbooks, handoffs, progress notes, TODO files, or scratch task lists to this public repository. Keep them outside a standalone clone or in the external planning workspace configured by the contributor. Documentation under docs/ must describe behavior present in the current code, except for one concise high-level roadmap.

pgGraph Source-Of-Truth Principle

PostgreSQL source tables are the source of truth. pgGraph should feel like a full graph layer, but graph-style operations must map to PostgreSQL-first behavior whenever they mutate data.

When adding graph write features:

  • expose graph ergonomics when labels, relationship types, properties, and identities can map cleanly to registered PostgreSQL tables and columns;
  • route writes through PostgreSQL DML first, so constraints, triggers, ACLs, RLS, MVCC, and indexes remain authoritative;
  • update pgGraph projections through sync, deltas, or rebuilds after the PostgreSQL write boundary accepts the change;
  • reject unmapped graph writes with clear errors and mapping guidance;
  • do not create durable graph-only state that can diverge from PostgreSQL as a second source of truth.