fable-eco

Fable Eco

Curated capability distribution and execution-control subsystem for get-fable.

Purpose

Bridge the gap between fragmented developer tool installation and disciplined agentic capability activation. fable-eco enforces the architectural principle of "install many, activate few": it provisions curated AI engineering capabilities (code graph indexers, review helpers, browser tools, testing runners) transactionally with immutable pinned versions and compiles task-bounded execution contracts for routed get-fable tasks under explicit least-privilege policy.

When to Use

• Discovering local machine runtimes, compilers, package managers, and coding host configurations without side effects.
• Resolving, planning, installing, updating, or rolling back curated ecosystem capabilities.
• Managing project capability bindings in .fable/eco.json to declare required capabilities, profiles, and minimum contract versions.
• Diagnosing or repairing ecosystem integrity, lockfiles, journals, or broken symlinks with non-mutating doctor checks.
• Compiling deterministic capability execution contracts for agent tasks based on lifecycle routing decisions.

When NOT to Use

• High-level lifecycle task routing or state management (use get-fable).
• Purely internal code authoring without external capability requirements (use fable-execute).
• Driving test-first red-green-refactor loops (use fable-tdd).
• Diagnosing repeated execution failures or broken test harnesses (use fable-recover).

Inputs

• routing_decision: Structured routing decision from fable_core::RoutingDecision containing selected skill, task shape, and intent.
• project_binding: Optional workspace binding from .fable/eco.json declaring active profiles, pinned capabilities, and policy overrides.
• catalog_layers: Multi-layer capability manifests across official distribution, team repositories, or local directories.
• machine_facts: Observed system runtimes, OS platform, package managers, and host configuration state.

Expected Outputs

• install_plan: Topological Directed Acyclic Graph (DAG) of installation operations with rollback classifications.
• lockfile: Cryptographically hashed .fable/eco.lock with SHA-256 digests and provenance metadata.
• execution_contract: Task-bounded manifest exposing only authorized tools, environment variables, and execution limits.
• capability_receipt: Structured record documenting host configuration edits, installed versions, and active ownership.

Procedure

1. Discovery: Run non-mutating probes to discover machine facts, installed runtimes, existing capability versions, and host configuration files.
2. Catalog Loading & Validation: Ingest capability and profile manifests across official, team, and local catalog layers, enforcing semantic schema validation.
3. Deterministic Resolution: Build dependency and conflict graphs, resolve transitive capability requirements, and detect incompatibilities or missing prerequisites.
4. Plan Generation: Construct an execution plan outlining all file copies, download extractions, environment updates, and health checks before applying any mutation.
5. Transactional Provisioning: Execute operations inside a staging sandbox with a write-ahead journal (.fable/eco-journal.json), verifying checksums and atomic commit.
6. Health Verification: Run post-installation health probes for each installed capability to prove operational readiness.
7. Receipt & Lock Sealing: Update .fable/eco.lock and write host configuration ownership receipts.
8. Contract Compilation: For routed tasks, filter installed capabilities against the routing decision and policy rules to compile an execution contract.

Decision Rules

• Plan before mutation: Never perform file modifications, downloads, or configuration edits without a verified pre-execution plan.
• Immutability on stable channel: Stable capabilities must resolve to immutable git commits or cryptographically hashed release archives (reject main or HEAD).
• Monotonic permission layering: Project policies can only restrict capabilities; project policies cannot override machine-wide deny rules.
• Least privilege capability activation: Expose only the specific capabilities required by the current lifecycle phase and task shape.
• Rollback on failure: If a health check or installation step fails during provisioning, trigger automated rollback using the transaction journal.

Tool Policy

• Execute discovery and resolution natively via the high-performance fable-eco Rust crate.
• Use atomic filesystem staging and copy operations with strict path traversal prevention (.. escapes prohibited).
• Execute read-only probes without altering system files or environment state.
• Validate all incoming manifests against canonical JSON Schema definitions in schemas/eco/.

Evidence Requirements

• Discovery results must include structured machine facts (OS, architecture, runtimes, package managers, hosts).
• Installation plans must list all operations with explicit id, kind, depends_on, and rollback_class.
• Execution contracts must specify exact capability IDs, permitted tools, network policies, and enforcement grades.
• Completed operations require passing post-install health check evidence before lockfile persistence.

Failure Handling

• When transaction staging fails or an unexpected crash occurs, classify journal state (Clean, RecoverableRollback, RecoverableCommit, Corrupted) and recover.
• If a required runtime or dependency is unavailable on the host machine, mark the capability as degraded or incompatible and report remediation steps.
• In case of conflicting capability requirements, halt resolution and output conflicting capability chains.

Completion Criteria

• All selected capabilities successfully staged, verified, and committed without unhandled errors.
• Target host configuration files patched cleanly with verified ownership tags.
• Post-install health checks pass with exit code 0 and valid output.
• Deterministic .fable/eco.lock generated and synchronized with workspace state.