{"id":47801987,"url":"https://github.com/byte271/aosp","last_synced_at":"2026-05-29T02:00:50.827Z","repository":{"id":345801602,"uuid":"1187438467","full_name":"byte271/aosp","owner":"byte271","description":"AOSP: AI-Operable Software Protocol — Shadow-first execution, temporal branching, and tamper-evident audit for AI actions","archived":false,"fork":false,"pushed_at":"2026-03-20T19:31:58.000Z","size":114,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-03T18:53:09.938Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://aosp-cli.pages.dev","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/byte271.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-03-20T18:15:51.000Z","updated_at":"2026-03-20T20:57:58.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/byte271/aosp","commit_stats":null,"previous_names":["byte271/aosp"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/byte271/aosp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/byte271%2Faosp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/byte271%2Faosp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/byte271%2Faosp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/byte271%2Faosp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/byte271","download_url":"https://codeload.github.com/byte271/aosp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/byte271%2Faosp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33633468,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-29T02:00:06.066Z","response_time":107,"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":"2026-04-03T17:06:00.220Z","updated_at":"2026-05-29T02:00:50.821Z","avatar_url":"https://github.com/byte271.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AOSP — AI-Operable Software Protocol\n\nA TypeScript framework for controlled AI execution. AOSP wraps every AI-initiated action in a structured lifecycle: **shadow-execute first, verify the diff, then commit to reality** — with full audit trails, policy enforcement, and rollback capability.\n\n## What It Does\n\nWhen an AI agent wants to take an action (write a file, call an API, modify a database), AOSP interposes a safety layer:\n\n1. **Shadow execution** — run the action in a sandbox, capture predicted side effects\n2. **Policy check** — evaluate against declarative rules (DSL) and risk thresholds\n3. **Approval gate** — route high-risk actions for human review\n4. **Commit** — apply the change to the real system\n5. **Trace** — record everything in a tamper-evident Merkle chain\n\nThis is the core loop. On top of it, AOSP adds **temporal branching** — the ability to fork execution into multiple parallel timelines, score all outcomes, and only commit the winner.\n\n## Core Modules\n\n### Kernel\nThe orchestrator. Wires together all modules and drives the 10-step execution lifecycle (identity validation, state fetch, risk assessment, policy evaluation, blast radius analysis, shadow execution, approval, commit, state update, trace recording).\n\n### Safety (`safe/`)\n- **PolicyEngine** — programmatic policy rules with risk-level gating\n- **PolicyDSL** — declarative rules like `DENY WHEN action MATCHES \"delete_*\"`\n- **ApprovalGateway** — human-in-the-loop approval for high-risk actions\n- **BlastRadiusAnalyzer** — graph-based impact analysis with transitive dependency tracking\n\n### Execution (`exec/`)\n- **ShadowExecutor** — preview actions without real side effects via pluggable adapters\n- **TransactionCoordinator** — atomic multi-step execution with ordered rollback\n- **PipelineEngine** — multi-stage pipelines with conditional branching and parallel stages\n- **TemporalBranchEngine** — parallel timeline exploration (see below)\n\n### Identity (`id/`)\n- **IdentityManager** — actor registration, trust levels, scope-based authorization\n\n### Trace \u0026 Audit (`trace/`)\n- **TraceStore** — structured event recording with query, export, and statistics\n- **MerkleChain** — append-only hash chain for tamper-evident audit trails with per-entry proofs\n\n### Observability (`info/`)\n- **StateManager** — surface state snapshots with history and diffing\n- **DriftDetector** — detect unauthorized out-of-band changes by comparing expected vs. actual state\n\n### Recovery (`magic/`)\n- **MagicRecovery** — automatic recovery strategies for failed operations\n\n### API (`api/`)\n- **ApiLayer** — JSON message transport for remote AOSP operations\n- **HttpServer** — HTTP server wrapping the API layer\n\n### Adapters (`adapters/`)\n- **FilesystemAdapter** — reference implementation for local filesystem operations (read, write, delete, list, mkdir) with shadow support and rollback\n\n### Persistence (`persist/`)\n- **PersistenceStore** — minimal, dependency-free key/value contract for durable audit state\n- **InMemoryPersistenceStore** — volatile backend for tests and ephemeral runs\n- **JsonFilePersistenceStore** — one JSON document per key with atomic writes (temp file + rename) so a crash mid-write never corrupts an existing snapshot\n\nThe `TraceStore` can `snapshot()` / `restore()` its full state (traces, event log, and Merkle chain), and `persist()` / `hydrate()` against any `PersistenceStore` — so the tamper-evident audit trail survives process restarts.\n\n### Compliance (`compliance/`)\n- **NistComplianceProfile** — maps AOSP's runtime safety mechanisms onto the four functions of the **NIST AI RMF 1.0** (Govern / Map / Measure / Manage), grades each control as satisfied / partial / unsatisfied, scores coverage, and emits an exportable JSON report with a prioritized gap list\n- **gatherEvidence** — derives a compliance evidence snapshot directly from a live AOSP instance\n\n### Bridge (`bridge/`)\n- **A2ASafetyBridge** — the trust layer for the Agent-to-Agent (A2A) protocol. A2A standardizes how agents *communicate*; the bridge decides whether a delegation should be *trusted*. It attributes a trust level to the originating agent (never honoring self-claimed trust by default) and routes the requested action through the full kernel lifecycle (shadow → policy → approval → commit) before any real effect occurs. *\"A2A handles communication. AOSP handles trust.\"*\n\n## Temporal Branching\n\nThe standout feature. Given an intent (e.g., \"set up a project\"), AOSP can:\n\n- **Fork** the intent into multiple competing strategies (minimal, standard, full-scaffold, etc.)\n- **Shadow-execute** all strategies in parallel, capturing predicted diffs for each\n- **Score** each timeline across 6 weighted dimensions: confidence, safety, minimality, completeness, speed, and reversibility — with auto-normalizing weights\n- **Rank** timelines with risk-aware tiebreaking (score → risk level → reversibility)\n- **Commit** only the winning timeline to reality\n- **Prune** losing timelines (with cascade to child branches)\n\nAdditional temporal features:\n\n- **Reality Merge Requests** — PR-style review objects with quorum-based approval and auto-expiry\n- **Pairwise Timeline Diffs** — side-by-side comparison of any two timelines with per-dimension breakdown\n- **Counterfactual Analysis** — \"what if we'd picked the other timeline?\" with avoided risks and sacrificed benefits\n- **Prevented Futures Report** — tracks timelines that were blocked (high risk, low confidence, budget exceeded, policy denied)\n- **Non-Selection Proofs** — SHA-256 hashed evidence of why each losing timeline lost, chained via Merkle-style hashing\n- **Branch Budgeting** — limits on timeline count, fork depth, total intents, and wall-clock time\n- **4 Pruning Strategies** — `score_threshold`, `confidence_decay`, `risk_ceiling`, `diminishing_returns` (independently configurable)\n- **Commit-Time Revalidation** — re-checks reality drift before merging\n- **Sandbox Mode** — explore alternate futures with no real mutations\n- **Future Search Engine** — query/filter timelines by score, risk, confidence, phase, name, surface\n- **Custom Safety Gate Checks** — register dynamic pre-merge validation functions\n- **Action Diffs** — structured per-action diff with content preview and size estimation\n- **Auto-Strategy Inference** — generate strategy variants from a single intent\n- **Exploration Statistics** — avg score, standard deviation, risk distribution, budget utilization\n\n## Quick Start\n\n```bash\n# Install dependencies\nnpm install\n\n# Build\nnpm run build\n\n# Run the interactive demo (12 steps covering the full feature set)\nnpm run demo\n```\n\n### Programmatic Usage\n\n```typescript\nimport { createAosp, createFilesystemSurface, FilesystemAdapter } from 'aosp';\n\nconst aosp = createAosp();\n\n// Register a surface (the thing being acted upon)\nconst surface = createFilesystemSurface('my-fs', 'My Filesystem', '/tmp/workspace');\naosp.kernel.registerSurface(surface);\naosp.executor.registerAdapter(new FilesystemAdapter('my-fs', '/tmp/workspace'));\n\n// Register an actor\naosp.identity.register({\n  id: 'agent-1', type: 'ai', name: 'My Agent',\n  trust: 'elevated', scopes: ['my-fs/*'],\n});\n\n// Execute with full lifecycle\nconst trace = await aosp.kernel.execute({\n  id: 'intent-1',\n  surface: 'my-fs',\n  action: 'write_file',\n  params: { path: 'hello.txt', content: 'Hello, world!' },\n  initiator: { id: 'agent-1', type: 'ai', name: 'My Agent', trust: 'elevated', scopes: ['my-fs/*'] },\n  timestamp: Date.now(),\n  metadata: {},\n});\n\nconsole.log(trace.status); // 'committed'\n```\n\n### Temporal Branching Usage\n\n```typescript\nconst { temporal, executor } = createAosp();\n\ntemporal.setExecModule(executor as any);\ntemporal.registerSurface(surface);\ntemporal.setBudget({ maxTimelines: 10, maxDepth: 3, maxTotalIntents: 50 });\n\nconst result = await temporal.explore([\n  { name: 'approach-a', intents: [/* ... */], metadata: {} },\n  { name: 'approach-b', intents: [/* ... */], metadata: {} },\n]);\n\nconsole.log(result.comparison.winner.name);  // best strategy\nconsole.log(result.stats.avgScore);           // exploration statistics\nconsole.log(result.explorationProofHash);     // tamper-evident hash\n\n// Commit the winner\nawait temporal.merge(result.comparison.winner.id);\n```\n\n### Durable Audit (Persistence)\n\n```typescript\nimport { createAosp, JsonFilePersistenceStore } from 'aosp';\n\nconst aosp = createAosp();\n// ... execute some actions ...\n\nconst backend = new JsonFilePersistenceStore('./aosp-audit');\nawait aosp.trace.persist(backend);          // snapshot traces + Merkle chain to disk\n\n// Later, in a fresh process:\nconst next = createAosp();\nawait next.trace.hydrate(backend);          // restore the verifiable audit trail\nconsole.log(next.trace.verifyChain().valid); // true\n```\n\n### NIST AI RMF Compliance\n\n```typescript\nimport { createAosp, gatherEvidence } from 'aosp';\n\nconst aosp = createAosp();\nconst report = aosp.nist.generateReport(gatherEvidence(aosp));\n\nconsole.log(report.summary.coverageScore); // 0–100\nconsole.log(report.summary.readiness);      // 'non-compliant' | 'developing' | 'substantial' | 'compliant'\nconsole.log(report.gaps);                   // prioritized recommendations\n```\n\n### A2A Safety Bridge\n\n```typescript\nconst aosp = createAosp();\n// ... register surface + adapter ...\n\n// Operator grants trust to a known remote agent (self-claimed trust is ignored).\naosp.bridge.registerAgent({ id: 'agent-a', name: 'Planner', trust: 'elevated', scopes: ['*'] });\naosp.identity.register({ id: 'agent-a', type: 'agent', name: 'Planner', trust: 'elevated', scopes: ['*'] });\n\nconst result = await aosp.bridge.mediate({\n  from: { id: 'agent-a', name: 'Planner', trust: 'elevated', scopes: ['*'] },\n  surface: 'my-fs',\n  action: 'write_file',\n  params: { path: 'out.txt', content: 'delegated work' },\n  task: 'persist the result',\n});\n\nconsole.log(result.decision);  // 'trusted' | 'rejected' | 'pending_approval' | 'error'\nconsole.log(result.committed); // whether it reached reality\n```\n\n## CLI\n\n```bash\n# Full lifecycle execution\naosp execute \u003csurface\u003e \u003caction\u003e [params...]\n\n# Shadow-only (preview)\naosp shadow \u003csurface\u003e \u003caction\u003e [params...]\n\n# Trace management\naosp trace list\naosp trace show \u003cid\u003e\naosp trace export [id]\n\n# Merkle chain\naosp chain verify\naosp chain show\n\n# Policy DSL\naosp policy add '\u003cexpression\u003e'\naosp policy list\n\n# NIST AI RMF compliance report (add --json for the full report)\naosp nist\naosp nist --json\n\n# System status\naosp status\n\n# Rollback\naosp rollback \u003ctraceId\u003e\n\n# Interactive demo\naosp demo\n```\n\n## Project Structure\n\n```\nsrc/\n  kernel/       Kernel orchestrator + type definitions\n  safe/         Policy engine, DSL, approval gateway, blast radius\n  exec/         Shadow executor, transactions, pipelines, temporal branching\n  id/           Identity and authorization\n  trace/        Trace store + Merkle chain (with snapshot/restore)\n  info/         State management + drift detection\n  magic/        Recovery strategies\n  api/          Transport layer + HTTP server\n  adapters/     Reference filesystem adapter\n  persist/      Durable persistence stores (in-memory + JSON file)\n  compliance/   NIST AI RMF compliance profile\n  bridge/       A2A safety bridge (cross-agent trust layer)\n  spec/         Protocol versioning\n  cli/          CLI with full lifecycle demo + `nist` report\n  index.ts      Public API exports + convenience factory\n```\n\nZero runtime dependencies beyond `chalk`, `commander`, and `uuid`. The test suite\n(`npm test`, Vitest) covers the kernel, safety, execution, trace/Merkle, persistence,\ncompliance, and A2A bridge modules.\n\n## Limitations\n\n- This is a protocol framework, not a production-ready system. It demonstrates the architecture for controlled AI execution.\n- The shadow execution model depends on adapters faithfully simulating actions. The included filesystem adapter is a reference implementation.\n- Temporal branching scores timelines based on shadow execution results. The scoring is only as good as the shadow predictions.\n- The Merkle chain and trace store are in-memory by default, but can be snapshotted and persisted via a `PersistenceStore` (a JSON-file backend ships in `persist/`); a higher-throughput deployment would add a database-backed store implementing the same interface.\n- The NIST compliance profile maps a curated, representative subset of AI RMF subcategories; it is a self-assessment aid, not a certified attestation.\n- Policy DSL supports basic patterns (`MATCHES`, `CONTAINS`, `==`, `!=`, `\u003e`, `\u003e=`, `\u003c`, `\u003c=`, `IN`). Complex policies should use programmatic rules.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbyte271%2Faosp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbyte271%2Faosp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbyte271%2Faosp/lists"}