{"id":30860384,"url":"https://github.com/selfapplied/tiq","last_synced_at":"2025-09-07T15:44:37.857Z","repository":{"id":313061888,"uuid":"1048980445","full_name":"selfapplied/tiq","owner":"selfapplied","description":null,"archived":false,"fork":false,"pushed_at":"2025-09-03T16:51:11.000Z","size":105,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-03T18:31:07.844Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/selfapplied.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":"2025-09-02T10:04:20.000Z","updated_at":"2025-09-03T16:51:14.000Z","dependencies_parsed_at":"2025-09-03T18:31:10.419Z","dependency_job_id":"e8c016f2-66be-4ead-9c72-0cdeb621fffc","html_url":"https://github.com/selfapplied/tiq","commit_stats":null,"previous_names":["selfapplied/tiq"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/selfapplied/tiq","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/selfapplied%2Ftiq","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/selfapplied%2Ftiq/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/selfapplied%2Ftiq/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/selfapplied%2Ftiq/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/selfapplied","download_url":"https://codeload.github.com/selfapplied/tiq/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/selfapplied%2Ftiq/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":274058947,"owners_count":25215200,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-07T02:00:09.463Z","response_time":67,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":"2025-09-07T15:44:23.484Z","updated_at":"2025-09-07T15:44:37.848Z","avatar_url":"https://github.com/selfapplied.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# TIQ - Timeline Interleaver \u0026 Quantizer\n\n⧗ A reversible Git repository management tool for dirs↔branches superposition.\n\n## Overview\n\nTIQ (Timeline Interleaver \u0026 Quantizer) is a sophisticated Git repository management tool that enables reversible superposition of directories as branches. It allows you to:\n\n- **Superpose**: Convert subdirectories into branches within a host repository\n- **Extract**: Extract branches back into standalone repositories  \n- **Map**: List all branches with their cryptographic passports\n- **Diff**: Compare histories between branches\n- **Classify**: In-memory mirror-kernel classification of branches vs ghost refs\n- **Emit**: Write mirror-kernel metadata to disk (JSON under .git)\n- **Reflect**: Persist mirror metadata into Git notes (no history rewrite)\n- **Rebalance**: Fast-forward heads to ghost refs when safe (no rewrite)\n- **Rotate**: Promote mirror state across scales (notes → metadata → files)\n\n## Key Features\n\n- **Reversible Operations**: All operations maintain full reversibility\n- **No History Rewrite**: Only adds refs/objects, never rewrites history\n- **Cryptographic Passports**: Each branch gets a unique cryptographic identity\n- **Clean State Enforcement**: Aborts on dirty repositories to maintain invariants\n- **Deterministic Branch Names**: Sanitizes directory names to valid Git branch names\n- **Non-Git Directory Support**: Can snapshot plain directories as orphan branches\n\n## CE1 Specification\n\nTIQ is defined by the following CE1 specification:\n\n```ce1\nCE1{\n  name=TIQ                      // Timeline Interleaver \u0026 Quantizer\n  glyph=⧗                       // tick\n  version=0.1\n  intent=dirs↔branches reversible.superposition\n\n  scope{\n    host=\".\"                    // aggregator repo (init if absent)\n    dirs.depth=1                // only first-level subdirs\n    ignore={\".git\",\".venv\",\"node_modules\"}\n  }\n\n  verbs{\n    superpose  = \"dirs → branch-per-dir (no rewrite)\"\n    extract    = \"branch → standalone repo at target\"\n    map        = \"list branches + heads + passports\"\n    diff       = \"compare histories: left..right\"\n  }\n\n  flags{\n    --include-non-git           // snapshot plain dirs as orphan branches\n    --prefix=\u003cpath\u003e             // snapshot under subpath\n    -e, --event                 // materialization predicates (content,cadence,size,host-moved)\n  }\n\n  passport{\n    tag = § blake3(tree(branch))[:8] \":\" crc16(meta)\n    cadence = per-branch-touch\n  }\n}\n```\n\n## Installation\n\n### Requirements\n\n- Python 3.7+\n- Git\n- Optional: `blake3` for enhanced cryptographic hashing\n\n### Install Dependencies\n\n```bash\n# Install with pip\npip install -r requirements.txt\n\n# Or install blake3 for enhanced hashing\npip install blake3\n```\n\n## Usage\n\n### Basic Commands\n\n```bash\n# Superpose directories as branches (sandbox-first)\npython tiq.py superpose\n\n# Include non-Git directories\npython tiq.py superpose --include-non-git\n\n# Map all branches with passports\npython tiq.py map\n\n# Extract a branch to standalone repository\npython tiq.py extract --branch my-branch --target /path/to/extract\n\n# Compare branch histories\npython tiq.py diff --left branch1 --right branch2\n\n# Classify mirror equilibrium (host vs ghost)\npython tiq.py classify\n\n# Emit a safe rebalance script (verifies invariants + FF-only)\npython tiq.py emit --out .git/tiq/rebalance.sh\n\n# Reflect mirror metadata into Git notes (CE1 format)\npython tiq.py reflect --mode notes --format ce1\n\n# Rebalance (FF-only) branches to their ghost refs\npython tiq.py rebalance\n\n# Rotate by scale\n#   notes: CE1 notes on commits\n#   metadata: tiq.branch.* keys in .git/config\n#   files: state committed to branch tiq/state (mirror.ce1 + rebalance.sh)\npython tiq.py rotate --mode notes\npython tiq.py rotate --mode metadata\npython tiq.py rotate --mode files\n```\n\n### Command Line Options\n\n- `--host \u003cpath\u003e`: Host repository path (default: \".\")\n- `--include-non-git`: Include non-Git directories as orphan branches\n- `--prefix \u003cpath\u003e`: Prefix for snapshot operations\n- `-e, --event`: Materialize predicate list: `content,cadence,size,host-moved`\n\n## Examples\n\n### Superposing Multiple Repositories\n\n```bash\n# Given directory structure:\n# project/\n# ├── frontend/     (Git repo)\n# ├── backend/      (Git repo)  \n# └── docs/         (plain directory)\n\n# Superpose all as branches (materialization is event-driven)\npython tiq.py superpose --include-non-git -e content\n\n# Result: project becomes a Git repo with branches:\n# - frontend\n# - backend  \n# - docs (orphan branch with snapshot)\n```\n\n### Extracting a Branch\n\n```bash\n# Extract the frontend branch to a new location\npython tiq.py extract --branch frontend --target ../frontend-extracted\n```\n\n### Mapping Branches\n\n```bash\n# List all branches with their passports\npython tiq.py map\n\n# Output:\n# Branch Map:\n# dir | type | branch | head | §\n# ----------------------------------\n# frontend | git | frontend | a1b2c3d | §f8a2b1c4:3e7d\n# backend | git | backend | e4f5g6h | §9c3d4e5f:2a8b\n# docs | snapshot | docs | i7j8k9l | §1b2c3d4e:5f6g\n```\n\n## Invariants\n\nTIQ maintains several critical invariants:\n\n1. **Idempotent Superpose**: Rerunning superpose results in zero-diff\n2. **Reversible Operations**: `extract(superpose(dir))` reproduces original repo\n3. **No History Rewrite**: Only adds refs/objects, never rewrites\n4. **Clean State Enforcement**: Aborts on dirty repositories\n5. **Deterministic Branch Names**: Sanitizes directory names consistently\n\n### Emergent properties\n\n- **Deterministic convergence**: Repeated superpose drives the host to a fixed point; subsequent runs plan no ops beyond changed children.\n- **Reversible views**: Branches behave like lossless views over directories; extract∘superpose preserves trees.\n- **Stable identities**: Passports `§{blake3:crc}` expose content drift at a glance while staying compact.\n- **Functorial mapping**: The mapping directory → branch preserves structure; fetch updates propagate without history rewrite.\n- **Object-store economy**: Git deduplicates objects across branches, making the superposed aggregate compact.\n- **Naming lattice**: `sanitize(dir)` yields deterministic branch names; collisions resolve predictably.\n- **Minimal-churn cadence**: Per-branch touch highlights only changed dirs in maps and reports.\n- **Diff-as-dynamics**: `left..right` operates as a temporal arrow between snapshots/children inside the host index.\n\n## Testing\n\nRun the comprehensive test suite:\n\n```bash\n# Run all tests\npython -m pytest test_tiq.py -v\n\n# Run specific test\npython -m pytest test_tiq.py::TestTIQInvariants::test_T1_fresh_host_n_repos_to_n_branches -v\n```\n\nThe test suite covers all T1-T5 invariants from the CE1 specification:\n\n- **T1**: Fresh host + N repos → N branches; heads set; passports present\n- **T2**: Rerun superpose --dry after --apply → no planned ops  \n- **T3**: Dirty child repo → ✖ and host untouched\n- **T4**: Extract(superpose(dir)) reproduces repo (tree hash equal)\n- **T5**: Snapshot mode (--include-non-git) → 1-commit branch with dir tree\n\n## Passport System\n\nEach branch receives a cryptographic passport with:\n\n- **Tag**: `§{blake3_hash[:8]}:{crc16_hash}`\n- **Head Short**: Short commit hash\n- **Date Short**: Commit date in YYYY-MM-DD format\n\nThe passport provides a unique, verifiable identity for each branch.\n\n## Error Handling\n\nTIQ enforces strict error handling:\n\n- **Dirty Repositories**: Aborts if any repository has uncommitted changes\n- **Missing Dependencies**: Graceful fallbacks for optional dependencies\n- **Invalid Operations**: Clear error messages for invalid operations\n- **Clean Abort**: Never leaves repositories in inconsistent states\n\n## Development\n\n### Project Structure\n\n```\ntiq/\n├── tiq.ce1          # CE1 specification\n├── tiq.py           # Core implementation\n├── test_tiq.py      # Test suite\n├── README.md        # This file\n├── pyproject.toml   # Python project configuration\n├── Makefile         # Build and test commands\n└── LICENSE          # License file\n```\n\n## Mirror Kernel (CE1: lens=MirrorKernel)\n\nThe mirror-kernel tracks Git metadata in memory by reflecting each branch `refs/heads/\u003cb\u003e` against its ghost `refs/tiq/ghost/\u003cb\u003e` produced during superpose. It reports per-branch statistics:\n\n- branch | host | ghost | ahead | behind | energy | eq | ff\n- **eq**: 1 if host head equals ghost head (axis equilibrium)\n- **ahead/behind**: commit counts (host-only vs ghost-only) via `rev-list --left-right --count`\n- **energy**: approximate churn computed from `diff-tree --numstat`\n- **ff**: 1 if host is ancestor of ghost (fast-forward possible)\n\nRun:\n\n```bash\npython tiq.py classify\n```\n\nThis is read-only and maintains all invariants: no working tree writes, no history rewrite.\n\n### Emitting Mirror Metadata\n\nBy default, the emit command writes to `.git/tiq/mirror.json`:\n\n```bash\npython tiq.py emit\n```\n\nCustom path and (currently only) JSON format:\n\n```bash\npython tiq.py emit --out /tmp/mirror.json --format json\n```\n\n### Building\n\n```bash\n# Run tests\nmake test\n\n# Check code quality\nmake lint\n\n# Build documentation\nmake docs\n\n# Clean build artifacts\nmake clean\n```\n\n## License\n\nTIQ is released under the MIT License. See [LICENSE](LICENSE) for details.\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Add tests for new functionality\n4. Ensure all tests pass\n5. Submit a pull request\n\n## Acknowledgments\n\nTIQ is inspired by the principles of reversible computation and the need for clean, deterministic repository management. The CE1 specification format provides a formal foundation for the tool's behavior and invariants.\n\n---\n\n*\"Every reversible plan can be cast as a TIQ operation. If Git comprises the universal version control system, then TIQ occupies the space of reversible repository transformations.\"*\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fselfapplied%2Ftiq","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fselfapplied%2Ftiq","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fselfapplied%2Ftiq/lists"}