{"id":47803272,"url":"https://github.com/mrizzi/symref","last_synced_at":"2026-04-03T17:16:49.998Z","repository":{"id":348685289,"uuid":"1199342156","full_name":"mrizzi/symref","owner":"mrizzi","description":"A Rust CLI for symbolic variable storage and dereferencing. Stores validated JSON as $VAR references and substitutes them on demand. Session-scoped, deterministic, no network/LLM.","archived":false,"fork":false,"pushed_at":"2026-04-02T10:22:54.000Z","size":32,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-03T00:28:19.334Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mrizzi.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-02T08:58:45.000Z","updated_at":"2026-04-02T10:22:58.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/mrizzi/symref","commit_stats":null,"previous_names":["mrizzi/symref"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/mrizzi/symref","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mrizzi%2Fsymref","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mrizzi%2Fsymref/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mrizzi%2Fsymref/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mrizzi%2Fsymref/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mrizzi","download_url":"https://codeload.github.com/mrizzi/symref/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mrizzi%2Fsymref/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31365443,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-03T17:13:05.644Z","status":"ssl_error","status_checked_at":"2026-04-03T17:13:04.413Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-04-03T17:16:49.239Z","updated_at":"2026-04-03T17:16:49.991Z","avatar_url":"https://github.com/mrizzi.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# symref\n\nSymbolic variable storage and dereferencing.\n\nsymref implements the **symbolic dereferencing** aspect of the Dual LLM pattern from the paper [Design Patterns for Securing LLM Agents against Prompt Injections](https://arxiv.org/pdf/2506.08837). In this pattern, a privileged LLM works with opaque `$VAR` references rather than raw untrusted content. symref manages the variable store and performs substitution at execution time.\n\n**Key properties:**\n- **Deterministic** -- no LLM, no network, pure data transformation\n- **Session-scoped** -- variables persisted in a JSON file per session\n- **Composable** -- designed to be called from shell hook scripts via stdin/stdout\n\n## Installation\n\n```bash\ncargo install --path .\n```\n\nOr build from source:\n\n```bash\ncargo build --release\n# Binary at target/release/symref\n```\n\n## Usage\n\nsymref exposes two subcommands: `store` and `deref`.\n\n### Store: ingest validated JSON and assign symbolic references\n\n```bash\nsymref store \\\n  --session /path/to/session-dir \\\n  --prefix X7F \\\n  --input validated.json\n```\n\nGiven this input (`validated.json`):\n\n```json\n{\n  \"requirements\": [\n    {\"id\": \"REQ_1\", \"summary\": \"OAuth2 login flow\", \"priority\": \"high\"},\n    {\"id\": \"REQ_2\", \"summary\": \"Session persistence\", \"priority\": \"medium\"}\n  ],\n  \"acceptance_criteria\": [\n    {\"id\": \"AC_1\", \"description\": \"Users can authenticate via OAuth2\"}\n  ]\n}\n```\n\nsymref assigns symbolic references and writes them to `\u003csession-dir\u003e/vars.json`:\n\n```json\n{\n  \"$X7F_REQ_1\": {\"id\": \"REQ_1\", \"summary\": \"OAuth2 login flow\", \"priority\": \"high\"},\n  \"$X7F_REQ_2\": {\"id\": \"REQ_2\", \"summary\": \"Session persistence\", \"priority\": \"medium\"},\n  \"$X7F_AC_1\": {\"id\": \"AC_1\", \"description\": \"Users can authenticate via OAuth2\"}\n}\n```\n\nAnd outputs a summary to stdout:\n\n```json\n{\n  \"refs\": {\n    \"$X7F_REQ_1\": { \"summary\": \"OAuth2 login flow\", \"ref\": \"$X7F_REQ_1\" },\n    \"$X7F_REQ_2\": { \"summary\": \"Session persistence\", \"ref\": \"$X7F_REQ_2\" },\n    \"$X7F_AC_1\": { \"summary\": \"Users can authenticate via OAuth2\", \"ref\": \"$X7F_AC_1\" }\n  },\n  \"store_path\": \"/path/to/session-dir/vars.json\"\n}\n```\n\nStdin also works:\n\n```bash\ncat validated.json | symref store --session ./session --prefix X7F\n```\n\n### Deref: substitute references with stored values\n\n```bash\nsymref deref \\\n  --session /path/to/session-dir \\\n  --input template.json\n```\n\nGiven this template:\n\n```json\n{\n  \"summary\": \"Implement OAuth2 login\",\n  \"description\": \"## Acceptance Criteria\\n- $X7F_AC_1\\n\\n## Requirements\\n- $X7F_REQ_1\"\n}\n```\n\nOutput (concrete values substituted):\n\n```json\n{\n  \"summary\": \"Implement OAuth2 login\",\n  \"description\": \"## Acceptance Criteria\\n- Users can authenticate via OAuth2\\n\\n## Requirements\\n- OAuth2 login flow\"\n}\n```\n\nPlain text works too:\n\n```bash\necho \"Implement $X7F_REQ_1\" | symref deref --session ./session\n```\n\n### Naming convention\n\n| Input field | Type | Variable name |\n|---|---|---|\n| `requirements[0]` | Array item | `$PREFIX_REQ_1` |\n| `acceptance_criteria[0]` | Array item | `$PREFIX_AC_1` |\n| `background` | Scalar | `$PREFIX_BACKGROUND` |\n\n- **Array fields**: `$PREFIX_ABBREV_N` where `ABBREV` is the first letter of each underscore-separated word (or first 3 chars for single words), and `N` is a 1-based index.\n- **Scalar fields**: `$PREFIX_FIELD` where `FIELD` is the full field name uppercased.\n\n### Substitution behavior\n\nWhen a stored value is a JSON object, the most representative field is used for substitution (checked in order: `summary`, `description`, `text`, `value`, then the first string field found).\n\nUnresolved `$VAR` references are left as-is in the output and logged as warnings to stderr.\n\nBoth `$VAR` and `${VAR}` syntax are supported.\n\n## Development\n\n```bash\n# Build\ncargo build\n\n# Test\ncargo test\n\n# Lint (full CI check)\ncargo +nightly fmt --check \u0026\u0026 \\\n  RUSTFLAGS=\"-D warnings\" cargo check \u0026\u0026 \\\n  cargo clippy -- -D warnings \u0026\u0026 \\\n  RUSTFLAGS=\"-D warnings\" cargo test\n```\n\n## Architecture\n\n```\nstore command:\n  input JSON --\u003e parse --\u003e assign $VAR names --\u003e append to vars.json --\u003e output refs\n\nderef command:\n  input text/JSON + vars.json --\u003e subst crate substitution --\u003e output concrete text/JSON\n```\n\nThe [subst](https://docs.rs/subst) crate provides the `$VAR`/`${VAR}` substitution engine. symref wraps it with a file-backed variable store, a CLI interface, and the store/deref commands.\n\n## Acknowledgements\n\nsymref is built on top of the [subst](https://crates.io/crates/subst) crate, which provides the `$VAR`/`${VAR}` substitution engine. Big thanks to its maintainers.\n\n## License\n\nSee [LICENSE](LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmrizzi%2Fsymref","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmrizzi%2Fsymref","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmrizzi%2Fsymref/lists"}